project-foundation

project-foundation protocol

Lightweight orchestrator of a project definition pipeline. You (the agent) are only the coordinator: you maintain state, load ONE phase contract at a time, delegate the heavy work to subagents, validate results, and persist progress.

What this skill is NOT

It does NOT reimplement Spec Driven Development. The responsibility ends where SDD begins.
It does NOT do heavy work in this context window: that goes to subagents (phase by phase).
It does NOT depend on conversational history: every phase must be able to run in a new session.

Commands

/project-foundation "idea o descripción"   # arranca nuevo pipeline (fase 0)
/project-foundation                        # reanuda desde state.yaml
/project-foundation status                 # solo dashboard, no ejecuta nada
/project-foundation review <fase>          # reabre una fase completada (cascada stale)
/project-foundation feature FEAT-006       # compila feature brief → .scratch/feature-briefs/
/project-foundation install-pack           # instala pack curado de superpoderes (UX/UI, arquitectura, grill-me)

Pipeline map

#	Phase (id)	Contract	Depends on	Main output
00	intake	phases/00-intake.md	—	initial state + level
01	research	phases/01-research.md	intake	docs/research/COMPETITIVE-ANALYSIS.md
02	product	phases/02-product.md	research*	PROJECT.md
03	domain	phases/03-domain.md	product	docs/product/DOMAIN.md
04	requirements	phases/04-requirements.md	product, domain	docs/product/REQUIREMENTS.md
05	use_cases	phases/05-use-cases.md	domain, requirements	docs/product/USE-CASE-MAP.md + use-cases/
—	GATE	phases/checkpoints/product-freeze.md	00–05	checkpoints.product_freeze
06	ux_ui	phases/06-ux-ui.md	product_freeze	docs/product/UX-UI.md
07	system_design	phases/07-system-design.md	product_freeze	docs/architecture/SYSTEM-DESIGN.md + adr/
08	roadmap	phases/08-roadmap.md	requirements, use_cases, system_design	docs/product/ROADMAP.md
—	GATE	phases/checkpoints/design-freeze.md	06–08	checkpoints.design_freeze
09	audit	phases/09-audit.md	design_freeze	docs/audit/FOUNDATION-AUDIT.md + TRACEABILITY.md
10	bootstrap	phases/10-bootstrap.md	audit approved	initial technical structure
11	agent_setup	phases/11-agent-setup.md	bootstrap	AGENTS.md + routing
12	sdd_init	phases/12-sdd-init.md	agent_setup	handoff to SDD

* research is conditional (research_mode: needed|skipped, decided in intake).

Depth profiles (decided in intake, respected by each contract)

Level	research	individual UCs	UX/UI	ADRs	Audit
prototype	skip (default)	main flow only	minimal (1 section)	almost never	lite
mvp	short	narrative	standard	only costly decisions	full
production	complete	narrative + edge cases	complete	3-condition rule	full
internal	skip (default)	narrative	minimal	only costly decisions	lite

Execution protocol (fixed steps of each phase)

Read .project-foundation/state.yaml. If it does not exist and there are args → phase 00. If it does not exist and there are no args → explain how to start. If it exists → continue.
Verify gates and dependencies of the target phase (according to the map). If a gate has not passed, run its checkpoint before continuing.
Read ONLY the contract of the current phase (phases/NN-*.md). Do not read other contracts.
Read ONLY the whitelisted inputs that the contract declares. Never read the entire project.
Execute the phase according to its contract (interview, delegation or mixed).
Validate outputs against the contract's exit criteria. If they do not pass, do not advance.
Update state.yaml (status, outputs, summary, history) according to references/state-schema.md.
Short checkpoint to the user (max 10 lines): what was produced, key decision, what comes next.
If the accumulated context is high (long interviews, several subagents), propose closing the session and continuing in a new one: the state persists and the next phase starts on its own.

Context rules (critical)

The orchestrator never reads the entire project unless the contract explicitly requires it.
Each phase declares its inputs; subagents receive ONLY those inputs.
Extensive outputs are written to files, never to the chat.
Subagents return only a compact YAML handoff (≤30 lines).
Every phase runs from a new session: never assume history is available.
Important information has a single source of truth (the document that defines it).
Do not load historical documents if the contract does not ask for them.

Interaction rules

Use the environment's interactive question tool if it exists (question, ask_user_question); if not, literate options. Never a plain-text interrogation.
Maximum 4 questions per round. Adaptive questions, not a fixed questionnaire.
F1–F4 filter before each question: tied to the phase objective / not answered / changes a real decision / does not open lateral fronts.
Do not ask what can be inferred or delegated to exploration. Propose defaults with justification and ask for confirmation instead of inventing questions.
If the user does not answer something non-critical: assume the safe path, mark it ASUMIDO in the document and continue. Only block if the decision is structural.
Allow going back at any time (review <fase>).

Delegation

Subagent prompts live as data in agents/ — they are rendered with the phase's whitelisted inputs and the per-environment mapping is in references/delegation-adapter.md.
Handoff contract for every subagent (≤30 lines):

phase: <fase>
status: completed | partial | failed
outputs: [rutas escritas]
summary: {métricas mínimas}
important_decisions: [máx 5, una línea c/u]
open_questions: [máx 5, solo las que bloquean]

A subagent NEVER returns entire documents to the orchestrator: it writes its output to its file and returns this handoff.

Injection of Enhancing Skills (Curated Pack)

To avoid AI's "regression to the mean" (generic interfaces, tutorial architectures), project-foundation supports injection of high-reputation skills (>100K installs):

UX/UI (Phase 06): design-taste-frontend, impeccable, web-design-guidelines.
Intake / Product (Phases 00, 02): grill-me (Socratic interrogation by Matt Pocock).
Architecture (Phase 07): improve-codebase-architecture (modularity and boundaries).

Automatic installation:

During Phase 00, the orchestrator asks only once whether you want to install them in batch.
Or by running at any time /project-foundation install-pack.
Or in Phase 06 (JIT): if the design skill is missing, the orchestrator installs it on the fly with npx -y skills add leonxlnx/taste-skill@design-taste-frontend -g -y. Full details in references/curated-skills-pack.md.

Gates, rework, and stale cascade

The gates (product_freeze, design_freeze) are orchestrator checklists + user confirmation. They are NOT immutable: reopening a phase marked behind the gate invalidates forward (stale: true in cascade according to the dependency map) and the user decides whether to re-execute or re-validate the affected phases.
The audit (phase 09) is the final independent verification. Its findings can reopen specific phases. Maximum 2 re-audit cycles; on the third, an explicit human decision (continue with documented gaps or reopen).

Preflight of sibling skills (phases 10 and 11)

Phase 10 reuses project-starter (technical-only mode) and phase 11 reuses agentmd-generator. Before those phases, verify presence in .agents/skills/, skills/ or ~/.agents/skills/. If missing, suggest: npx skills add AgustinAlbonico/ai-customizations --skill <skill> --agent <agente> -y and wait for the user to install. Never reimplement its logic.

State and tools

Schema, writing rules, and stale semantics: references/state-schema.md.
Optional validator: assets/state-tool.sh / assets/state-tool.ps1 (validate | integrity | show). Use it after each state write if available; if not, respect the schema by hand.

Pipeline closure

Upon completing phase 12, project-foundation is removed: the features are worked on with the flow SDD of the environment (e.g., Gentle AI: sdd-explore → sdd-new → spec → design → tasks → apply → verify), powered by /project-foundation feature FEAT-XXX (see references/feature-intake.md).