Project Init

Run this workflow only for greenfield initialization.

1. Mode Guard

Before interviewing, check:

1. If both docs/architecture.md and docs/plans.md exist, stop and switch to project-update.
2. If docs are missing but code roots/manifests exist (src/, app/, apps/*/src, package.json, etc.), stop and switch to project-convert.
3. Continue only when docs are missing and codebase signals are absent.

2. Interactive Interview

Collect requirements before generating any docs:

1. Ask project name and core goals.
2. Run one market snapshot (similar products, patterns to reuse/avoid).
3. Draft project intro + end-to-end core flow and confirm with the user.
4. Propose 3-4 architecture + visual directions; get user choice.
5. Run clarifying rounds (user journeys, components, stack, deployment, constraints).
6. Assign complexity tier (Standard by default; Complex only when justified) and confirm.
7. Provide final synthesis; require explicit user approval before writing files.

3. 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:

1. Keep docs/architecture.md as the stable product/technical source of truth.
2. Keep docs/plans.md milestone-driven and ensure Production Readiness Gate is the final milestone.
3. Keep docs consistent with each other; never leave unresolved contradictions.
4. In docs/implement.md, add mandatory sections:
   • First-Principles Execution
   • Atomic Task Execution
   • Rewrite-First Policy
   • No-Compatibility Rule
5. In docs/plans.md, every task must include Commit Boundary: exactly one atomic commit.
6. 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:

1. Use first-principles execution: solve root causes from requirements and architecture, not superficial patches.
2. Treat task and sub-task as the same execution unit.
3. Enforce one task -> one atomic commit.
4. Finish the full task scope before commit: all affected code, tests, configs, scripts, and docs.
5. Follow code is cheap: if a module becomes hard to fix cleanly, delete and rewrite the module.
6. Do not add compatibility code (adapter, shim, dual-path logic, deprecated aliases, temporary compatibility flags).
7. If a rewrite changes interfaces, fix all impacted callers in the same task.
8. Do not leave breakage for a follow-up task just to preserve compatibility.

4. Review Protocol

Run all review gates before handoff:

1. Tier review:
   • Standard: Agent 2 + Agent 3
   • Complex: Agent 1 + Agent 2 + Agent 3
2. Mandatory cross-model review via mcp__codex__codex on docs/architecture.md + docs/plans.md.
3. Apply valid findings and re-check consistency.
4. 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.

5. Hooks Installation (Mandatory)

Before final messaging, auto-install hooks:

1. Detect package manager:
   • bun.lock -> bun
   • pnpm-lock.yaml -> pnpm
   • yarn.lock -> yarn
   • otherwise npm
2. Resolve installer path in this order:
   • scripts/setup-hooks.sh
   • ../full-project-skill/scripts/setup-hooks.sh
3. Run:

bash <resolved-setup-hooks-path> --pm <detected-pm> --project-dir <project-dir> --platform both

4. If no installer path exists, ask the user where their hook installer lives and stop.
5. If installation fails, show the error and stop for user resolution.

6. Final Handoff

Tell the user:

1. Docs are ready under docs/.
2. Hooks are installed to .claude/ and .codex/.
3. They should review docs/architecture.md + docs/plans.md.
4. Execution should follow docs/implement.md.
5. Work is complete only after passing the Production Readiness Gate milestone.