Project Init
Run this workflow only for greenfield initialization.
- Mode Guard
Before interviewing, check:
-
If both docs/architecture.md and docs/plans.md exist, stop and switch to project-update .
-
If docs are missing but code roots/manifests exist (src/ , app/ , apps/*/src , package.json , etc.), stop and switch to project-convert .
-
Continue only when docs are missing and codebase signals are absent.
- Interactive Interview
Collect requirements before generating any docs:
-
Ask project name and core goals.
-
Run one market snapshot (similar products, patterns to reuse/avoid).
-
Draft project intro + end-to-end core flow and confirm with the user.
-
Propose 3-4 architecture + visual directions; get user choice.
-
Run clarifying rounds (user journeys, components, stack, deployment, constraints).
-
Assign complexity tier (Standard by default; Complex only when justified) and confirm.
-
Provide final synthesis; require explicit user approval before writing files.
- Generate Documentation
After user confirmation, create/update:
-
docs/architecture.md
-
docs/plans.md
-
docs/implement.md
-
docs/secrets.md
-
docs/documentation.md
-
docs/design.md
-
docs/decisions.md (for Standard/Complex tiers)
-
tasks/todo.md
-
tasks/lessons.md
-
CLAUDE.md
-
AGENTS.md
Rules:
-
Keep docs/architecture.md as the stable product/technical source of truth.
-
Keep docs/plans.md milestone-driven and ensure Production Readiness Gate is the final milestone.
-
Keep docs consistent with each other; never leave unresolved contradictions.
-
In docs/implement.md , add mandatory sections:
-
First-Principles Execution
-
Atomic Task Execution
-
Rewrite-First Policy
-
No-Compatibility Rule
-
In docs/plans.md , every task must include Commit Boundary: exactly one atomic commit .
-
In tasks/todo.md , every task must include Task ID and Commit Status (pending or done ).
3.5. Implementation Discipline (Mandatory)
Apply these rules to every implementation task generated by this workflow:
-
Use first-principles execution: solve root causes from requirements and architecture, not superficial patches.
-
Treat task and sub-task as the same execution unit.
-
Enforce one task -> one atomic commit .
-
Finish the full task scope before commit: all affected code, tests, configs, scripts, and docs.
-
Follow code is cheap : if a module becomes hard to fix cleanly, delete and rewrite the module.
-
Do not add compatibility code (adapter , shim , dual-path logic, deprecated aliases, temporary compatibility flags).
-
If a rewrite changes interfaces, fix all impacted callers in the same task.
-
Do not leave breakage for a follow-up task just to preserve compatibility.
- Review Protocol
Run all review gates before handoff:
-
Tier review:
-
Standard: Agent 2 + Agent 3
-
Complex: Agent 1 + Agent 2 + Agent 3
-
Mandatory cross-model review via mcp__codex__codex on docs/architecture.md
- docs/plans.md .
-
Apply valid findings and re-check consistency.
-
Ask user for one annotation pass on docs/architecture.md and docs/plans.md , resolve notes, and wait for explicit "ready".
If mcp__codex__codex is unavailable, do not skip silently. Ask user to choose manual checklist path or alternate-model path and record which was used.
- Hooks Installation (Mandatory)
Before final messaging, auto-install hooks:
-
Detect package manager:
-
bun.lock -> bun
-
pnpm-lock.yaml -> pnpm
-
yarn.lock -> yarn
-
otherwise npm
-
Resolve installer path in this order:
-
scripts/setup-hooks.sh
-
../full-project-skill/scripts/setup-hooks.sh
-
Run:
bash <resolved-setup-hooks-path> --pm <detected-pm> --project-dir <project-dir> --platform both
-
If no installer path exists, ask the user where their hook installer lives and stop.
-
If installation fails, show the error and stop for user resolution.
- Final Handoff
Tell the user:
-
Docs are ready under docs/ .
-
Hooks are installed to .claude/ and .codex/ .
-
They should review docs/architecture.md
- docs/plans.md .
-
Execution should follow docs/implement.md .
-
Work is complete only after passing the Production Readiness Gate milestone.