init-project

name

init-project

description

Stage 0 — grill the user to settle the repo constitution: architecture, coding patterns, domain language, dependency choices, and tooling configuration. Produces CONTEXT.md (domain glossary + tooling config) and ADRs (architectural decisions). MUST be run before `/drive-outcomes` on any project. Use when the user says "/init-project", "set up the project constitution", "initialize the repo for the pipeline", or on a fresh project checkout before any planning begins.

Init Project

Stage 0 of the ODD pipeline. Establishes the repo constitution — the shared vocabulary, architectural principles, tooling configuration, and hard-to-reverse decisions that all downstream stages will reference. Without this, every session re-litigates patterns and terms, wasting tokens and producing inconsistent design.

The constitution serves two audiences: agents (as operational context for decision-making) and humans (as documented proof to push back when agents drift). Both must be able to read and reference it.

Trigger

/init-project [project-root]

Where [project-root] defaults to the current repo root. Run once per project, before any /drive-outcomes or /make-judgement sessions.

Pre-flight

Check for existing constitution:

cat CONTEXT.md 2>/dev/null || echo "NO_CONTEXT_MD"
fd -e md . docs/adr/ 2>/dev/null || echo "NO_ADRS"

If CONTEXT.md already exists and ADRs are present, confirm with the user: "Constitution already exists. Re-run to update, or skip if the existing one is still current?"

References

• Context format: {PLUGIN_ROOT}/skills/define-outcomes/references/context-format.md
• ODD pattern: {PLUGIN_ROOT}/skills/drive-outcomes/references/odd-pattern.md

Output

• CONTEXT.md — domain glossary with precise definitions, flagged ambiguities, and tooling configuration (build/test/lint commands)
• docs/adr/{NNNN}-{slug}.md — architecture decision records (created sparingly, only when hard-to-reverse, surprising, and the result of a real trade-off)

Process

Step 1: Setup

Gather initial project info:

git remote -v 2>/dev/null
fd -t f --max-depth 3 | head -40

Detect existing build system:

• Cargo.toml → Rust
• pyproject.toml / setup.py / requirements.txt → Python
• package.json → Node/TypeScript
• go.mod → Go
• Makefile / CMakeLists.txt → C/C++
• pom.xml / build.gradle → Java

Step 1.5: Resolve Agent Mapping

The pipeline uses pluggable agents. Determine which agent to use for grilling:

1. Check CLI args: If the user's invocation includes --agent-griller=<agent-name>, use that agent. CLI args override everything.
2. Check AGENT_CONFIG.md: Read AGENT_CONFIG.md from the project root. If it exists, parse **griller:** <agent-name>. Apply if not already set by CLI args.
3. Apply default: If still unset, griller defaults to general-purpose.
4. Build resolved mapping: Record which agent will be used for griller.

Throughout this skill, whenever a subagent is launched, use the resolved agent name.

Step 2: Grill — Settle the Constitution

Launch a grill-me subagent that interviews the user, one question at a time, with the agent providing recommended answers. The griller explores the codebase to ground every question in real code.

Agent: {griller} (subagent, discardable context)

Task: Grill the user to establish the project constitution.

Context:

• Domain glossary format: {PLUGIN_ROOT}/skills/define-outcomes/references/context-format.md
• ODD pattern: {PLUGIN_ROOT}/skills/drive-outcomes/references/odd-pattern.md
• Detected language/build system: {LANG_DETECT}

Work through these areas in order. For each, propose specific answers based on codebase exploration and ask the user to confirm.

Area 1: Project purpose

What is this project building? Who is it for? What problem does it solve?

Explore: read the project's build config (Cargo.toml, pyproject.toml, package.json, etc.) description field, README, any existing docs.

If the project builds on specific science/domain knowledge (DFT, quantum chemistry, etc.), establish that here — it shapes every downstream decision.

Area 2: Domain language

What terms are central to this project's domain? For each:

• Propose a precise definition
• List aliases to avoid
• Check if existing code uses the term consistently

Explore: read module names, type names, function names from key source files. Read key source files to verify actual usage.

Update CONTEXT.md inline as each term is resolved. Create it lazily when the first term is settled.

Area 3: Architecture

What are the module/package boundaries? What belongs where?

Explore: read the module/package tree from source files. Check existing boundary decisions (what's public vs private, which packages depend on which).

Decisions to settle:

• Monorepo vs multi-repo? (Already decided — you're in a workspace.)
• Layered or flat package structure?
• Which package owns the domain types?
• Where do I/O adapters live?
• Shared types package or per-package types?

Area 4: Dependencies and tooling

Which libraries/packages should the project use for common patterns?

Explore: check build config files for existing dependencies. Read current usage to see what's already in play.

Decision tree (propose based on project type and detected language):

• Parser project: Which parsing library is idiomatic for this language?
• Serialization: JSON, YAML, TOML, binary? Which library is the ecosystem standard?
• Error handling: typed errors vs context-wrapped errors? What does the ecosystem prefer?
• Numerics/linear algebra: Which library is idiomatic for this language?
• CLI: Which argument parsing library?
• Testing: Which framework for property-based or fuzz testing?

Explore the relevant package registry (crates.io, PyPI, npm, etc.) for established solutions before deciding to build custom.

Area 4b: Tooling (Language-Specific Configuration)

After dependencies are settled, capture the concrete build/test/lint commands:

• Language: {rust | python | typescript | go | c | ...}
• Build command: What command checks/compiles the project? (e.g., cargo check --workspace 2>&1)
• Test command: What command runs the full test suite? (e.g., cargo test --workspace 2>&1)
• Lint command: What command runs the linter? (e.g., cargo clippy --workspace -- -D warnings 2>&1)
• File extensions: What file extensions does this project use? (e.g., .rs)
• Test file patterns: Where are test files? (e.g., tests/**/*.rs src/**/*.rs)
• Test filter flag: How to run a single test by name? (e.g., -p <package> <test_name>)
• Package manager: (e.g., cargo, npm, pip, go mod)
• Package boundaries: How is the project organized into sub-components?

Write these into CONTEXT.md under a ## Tooling section using the format at {PLUGIN_ROOT}/skills/define-outcomes/references/context-format.md.

Area 5: Coding patterns

What conventions should downstream agents follow?

Explore: read existing source files for actual style patterns used.

Decisions to settle:

• Error handling pattern (typed errors vs context-wrapped errors?)
• Module visibility (flat with re-exports vs deep nesting?)
• Async strategy (async/await, coroutines, threading, sync-only?)
• Testing conventions (unit tests inline, integration tests in tests/ directory?)
• Documentation conventions (docstrings on all public items? README per package?)
• Naming conventions (snake_case, camelCase, PascalCase?)

Area 6: Downstream pipeline expectations

Which pipeline stages will this project use, and in what order?

Decisions to settle:

• First phase: what's the most valuable thing to build first?
• Ground truth: what fixture files exist or need to be created?
• Review cadence: after every group? after every phase? PR-based?

After these stage decisions, ask the user:

The ODD pipeline supports pluggable agents. You can override which agent handles each role (executor, reviewer, architect, griller) by creating an AGENT_CONFIG.md in the project root. This is optional — shipped defaults work fine for most projects. Would you like me to generate one now, or skip?

If the user agrees, write AGENT_CONFIG.md to the project root with the four roles mapped to shipped defaults:

# Agent Configuration

**executor:** odd-pipeline:implementation-executor
**reviewer:** odd-pipeline:strict-code-reviewer
**architect:** odd-pipeline:software-architect
**griller:** general-purpose

If the user declines, mention they can create it later using the format documented in the ODD pipeline README.

Terminology validation — challenge against the glossary:

• If the user uses a term that conflicts with a settled definition, call it out immediately.
• When the user uses vague or overloaded terms, propose a precise canonical term and confirm it.
• Cross-reference claims about how the system works against actual code. If you find a contradiction, surface it.

ADR creation — offer sparingly:

• Only offer to create an ADR when ALL THREE are true:
  1. Hard to reverse — changing it later would be expensive
  2. Surprising without context — a future reader will wonder why
  3. Result of a real trade-off — genuine alternatives existed
• If any criterion is missing, skip the ADR. Record in CONTEXT.md instead.
• When an ADR is warranted: scan docs/adr/ for highest number, increment by one, create docs/adr/{NNNN}-{slug}.md.

After each question, provide your recommended answer. Continue until all six areas are resolved and the user confirms shared understanding.

Output: {will be captured by the orchestrator; the griller updates CONTEXT.md and creates ADRs inline as decisions crystallise}

Step 4: Synthesize

After the grill completes, verify all outputs are coherent:

1. Read CONTEXT.md — does it read as a single consistent glossary with tooling config?
2. Scan docs/adr/ — are ADRs properly numbered? Does each reference valid decisions that were actually discussed?
3. Does the constitution cover all six areas? If any were skipped, flag them.
4. Do factual claims in CONTEXT.md and ADRs carry verification granularity (what level of detail was verified), citation (file:line reachable in ≤60 seconds), and counter-example / test-fixture scope (what input distribution exercised the claim)? Without these, claims auto-classify as DERIVED in downstream sessions and cannot serve as success criteria.

Write a session summary:

# Project Constitution: {Project Name}

**Established**: {date}

## Areas Covered

- **Domain language**: {N} terms defined, {N} ambiguities resolved
- **Architecture**: {N} module/package boundaries, {N} ADRs created
- **Dependencies**: {N} library choices settled
- **Tooling**: build/test/lint commands configured for {language}
- **Coding patterns**: {N} conventions established
- **Pipeline expectations**: {N} decisions

## ADR Index

{List of ADRs created during this session — number, title, one-line summary}

Step 5: Handoff

Stage the artifacts:

git add CONTEXT.md 2>/dev/null
git add docs/adr/ 2>/dev/null
git commit -m "docs: establish project constitution ($(basename $PWD))"

Report to the user:

"Project constitution established for {Project Name}.

• CONTEXT.md — {N} domain terms defined, {language} tooling configured
• docs/adr/ — {N} architecture decision records

The constitution is committed. Downstream stages (/drive-outcomes, /make-judgement) will reference it automatically for language-specific commands.

Next steps:

1. /define-outcomes — define what the next phase should accomplish
2. /drive-outcomes <phase-plan> — start the first phase with ground-truth anchoring
3. Review the constitution yourself — it's your source of truth for pushing back when agents drift"

Boundaries

Will:

• Grill all six areas (purpose, language, architecture, dependencies, tooling, patterns, pipeline expectations)
• Detect the project's language/build system automatically
• Capture language-specific build/test/lint commands in CONTEXT.md
• Explore the codebase to ground every question in real code
• Update CONTEXT.md inline as terms are resolved
• Create ADRs sparingly — only when all three criteria are met
• Propose specific recommendations based on codebase exploration and domain knowledge
• Act as domain expert: suggest existing libraries, established patterns, known solutions before building custom
• Re-verify factual claims from subagent summaries by reading cited sources directly before taking action on them

Will not:

• Write any implementation code
• Decompose into tasks (that's /drive-outcomes)
• Create ADRs unnecessarily (if it's not surprising or not a trade-off, skip it)
• Accept vague language without proposing a precise term