mahmoud20138 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:
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:
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:
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:
- Never claim a result that was not produced by a recorded command, test, or source.
- Never invent data, API fields, credentials, coverage, metrics, repository features, licenses, or citations.
- If evidence is missing, write
UNKNOWN,UNVERIFIED, orBLOCKED. - Cite file paths, section numbers, URLs, commands, commits, manifests, or tests for important claims.
- Separate facts, calculations, observations, assumptions, proposals, and unknowns.
- Keep the critical product path runnable without AI, MCP, or external search.
- Use schemas and validation for AI-generated structured data.
- Require human review for high-impact decisions and external actions.
- Treat
INCONCLUSIVEas a valid result. - Do not advance a project gate without verified acceptance criteria.
Required agent response format
Require every future implementation agent to report:
## 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.