# Software Project Governance > Create a software-first project governance pack before starting any software, data, research, automation, or AI project. Use when a project needs a clear idea, implementation plan, executable product contract, agent instructions, anti-hallucination controls, tool and plugin guidance, MCP boundaries, reproducible state, and acceptance tests. - Skill: `mahmoud20138/software-project-governance` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add mahmoud20138/software-project-governance` - Raw SKILL.md: https://api.skillmd.com/api/skills/mahmoud20138/software-project-governance/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: mahmoud20138 (https://skillmd.com/u/mahmoud20138) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/mahmoud20138/software-project-governance --- # Software Project Governance ## Purpose Use this skill before starting a complex project when the user needs more than a vague plan. It converts an idea into a controlled project pack that guides an AI agent or engineering team toward an executable, testable, reproducible product. The skill is domain-independent. It can be used for a web application, Python service, data platform, research system, automation workflow, mobile app, desktop tool, API, AI product, or internal business system. > The generated Markdown files are control documents. The final product is not complete until the documents have been converted into working software, commands or endpoints, persistent outputs, automated tests, and a reproducible release or run. ## When to use Use this skill when the user asks to turn an idea into software, create a full implementation plan, use existing tools or MCP, keep an AI coding or research agent on track, reduce hallucinations, define exactly what the final product must do, or generate project documentation before coding. Do not use this skill for a small one-file edit, a simple question, or a short conversational answer. ## Required output pack Create these files inside the project’s `docs/` directory: ```text docs/ ├── 01_source_requirements.md ├── 02_software_implementation_plan.md ├── 03_tool_stack_and_existing_projects.md ├── 04_external_research_notes.md ├── 05_software_product_contract.md ├── 06_agent_operating_guide.md └── 07_skills_plugins_mcp_guide.md ``` Create these repository-control files: ```text AGENTS.md state/project_state.yaml state/active_task.md state/decision_log.md state/evidence_log.md ``` If the user provides an original plan, file, or specification, preserve it unchanged in `docs/sources/` and copy or summarize it into `01_source_requirements.md`. Never overwrite the user’s source document silently. ## Authority hierarchy Use this precedence when making decisions: ```text User-provided requirements and constraints ↓ Software product contract ↓ Software implementation plan ↓ Tool-stack and existing-project guide ↓ External research notes ↓ AI-generated proposals ``` The AI model is never the source of truth. If documents conflict, record the conflict in the decision log and ask for clarification or mark the work `BLOCKED`. ## Workflow ### Phase 1: Understand the project Extract the core idea, intended users, problem, required actions, inputs, outputs, operating modes, privacy and security constraints, licensing constraints, target platform, external services, integrations, non-goals, and success definition. If the product’s central purpose is unclear, ask one focused question before proceeding. Do not guess the main user outcome. ### Phase 2: Define the software product contract Write `05_software_product_contract.md` before writing a long implementation plan. Specify input schemas, output schemas, commands, endpoints, screens, failure states, deterministic behavior, persistence, lineage, versioning, AI boundaries, security boundaries, automated tests, and definition of done. The product must return an explicit status when it cannot produce a trustworthy answer. It must not fill missing information with invented values. ### Phase 3: Write the implementation plan Write `02_software_implementation_plan.md` with the product scope, non-goals, architecture, modules, data model, flows, configuration, commands or endpoints, UI pages, testing, deployment, phases, promotion gates, risks, stop conditions, and definition of done. The plan must describe how to build the product, not merely describe the idea. ### Phase 4: Select tools and existing projects Write `03_tool_stack_and_existing_projects.md`. For every recommended library, plugin, platform, or open-source repository, record the problem solved, role, adopt/build/optional/later status, maintenance signal, license, security considerations, integration boundary, required tests, and reason for selection. Search official documentation and repositories before making current claims. Do not add a dependency because it is popular. Add it only when it solves a named requirement and has a verification plan. ### Phase 5: Record research and evidence Write `04_external_research_notes.md` with source URLs, retrieval dates, verified facts, uncertainties, and recommendations. Separate source-confirmed facts from interpretation. Use the labels `SOURCE_CONFIRMED`, `CALCULATED`, `OBSERVED`, `ASSUMPTION`, `PROPOSAL`, `UNVERIFIED`, and `BLOCKED`. Never present an assumption, proposal, or unverified claim as fact. ### Phase 6: Create agent controls Write `06_agent_operating_guide.md` and `AGENTS.md`. Require agents to read the operating rules, project state, active task, and relevant source sections before changing code. Require acceptance criteria, allowed files, assumptions, tests, evidence, and blockers before completion. The agent must make the smallest coherent change, preserve source lineage, run tests, update project state and decision logs, and stop when evidence is missing or a test failure is not understood. ### Phase 7: Define skills, plugins, and MCP boundaries Write `07_skills_plugins_mcp_guide.md`. Map each integration to a specific purpose such as code management, documentation lookup, source discovery, scheduling, browser QA, notifications, deployment, or collaboration. Keep critical product behavior in tested project code. MCP must not be the source of truth for core calculations, model metrics, data lineage, or final outputs. Before enabling a connector, record its purpose, credentials boundary, data exposure, license, approval, and acceptance test. Enable only what the active task needs. ### Phase 8: Create project state Create `state/project_state.yaml` with the project name, mission, current phase, status, active task, completed tasks, next tasks, blocked tasks, required gates, last verified commit, last artifact or data manifest, and last test result. Create `state/active_task.md` with the task, phase, source sections, acceptance criteria, files allowed to change, forbidden changes, assumptions, and unresolved questions. Create `state/decision_log.md` and `state/evidence_log.md` for durable records. ### Phase 9: Validate the project pack Verify that all required files exist, the product contract contains executable inputs and outputs, the implementation plan contains a build sequence, the tool guide distinguishes adopted and custom components, the research notes contain sources and uncertainty labels, the agent guide contains stop conditions and reporting format, the MCP guide defines allowed and forbidden usage, project state identifies the next task, and no document falsely claims that software exists before code and tests exist. ## Universal anti-hallucination rules Include these rules in `AGENTS.md` and the agent operating guide: 1. Never claim a result that was not produced by a recorded command, test, or source. 2. Never invent data, API fields, credentials, coverage, metrics, repository features, licenses, or citations. 3. If evidence is missing, write `UNKNOWN`, `UNVERIFIED`, or `BLOCKED`. 4. Cite file paths, section numbers, URLs, commands, commits, manifests, or tests for important claims. 5. Separate facts, calculations, observations, assumptions, proposals, and unknowns. 6. Keep the critical product path runnable without AI, MCP, or external search. 7. Use schemas and validation for AI-generated structured data. 8. Require human review for high-impact decisions and external actions. 9. Treat `INCONCLUSIVE` as a valid result. 10. Do not advance a project gate without verified acceptance criteria. ## Required agent response format Require every future implementation agent to report: ```markdown ## Task ## Source sections used ## Plan ## Files allowed to change ## Changes made ## Evidence ## Tests run ## Unverified or blocked items ## Acceptance criteria status ## Next step ``` ## Software-first completion rule A project is not complete when its documents are polished. It is complete only when the documents have been converted into an executable package or application with defined inputs, defined outputs, commands, endpoints or screens, persistent and versioned results, automated tests, error and status handling, and a reproducible build or run. A notebook, mock, manually generated screenshot, prompt-only workflow, or untested prototype must be labeled `INCOMPLETE`. ## Resources Use `references/project-pack-spec.md` for the required contents of each generated file. Use `templates/` for repository-control templates. Use `scripts/create_project_pack.py` for deterministic creation of the initial directory and control files.