Project Convert

Run this workflow for existing repositories that need structured workflow bootstrap.

1. Mode Guard

Use this skill when:

• docs/architecture.md and docs/plans.md are missing.

• Codebase signals exist (src/ , app/ , apps//src , packages//src , services/*/src , package.json , pyproject.toml , go.mod , Cargo.toml ).

If docs already exist, switch to project-update . If docs and codebase signals are both absent, switch to project-init .

2. Discovery Baseline (Read-Only)

Build factual baseline before writing docs:

• Discover all code roots in monorepo/single-repo layouts.

• Map runtime shape: entry points, routes/API surfaces, modules, data/storage/integrations.

• Detect existing docs fragments (README , ad-hoc notes) and reusable information.

• Detect missing workflow assets (docs/ , tasks/ , .claude/hooks/ , .codex/hooks/ ).

• Summarize current reality and gaps to user; require baseline confirmation.

3. Conversion Profile

Classify profile and let user override:

• Baseline Conversion: bootstrap docs/hooks for current behavior (2-4 rounds)

• Upgrade Conversion: bootstrap plus planned structural upgrades (3-6 rounds)

If scope grows, reclassify and announce.

4. Focused Convert Interview

• Confirm discovered current-state behavior with user.

• Run profile-scoped clarifying rounds.

• Provide synthesis and require explicit approval before writing docs.

5. Documentation Bootstrap

Generate workflow docs from actual code reality:

• docs/architecture.md (include current-state snapshot + known divergences)

• docs/plans.md (conversion milestones, final Production Readiness Gate milestone)

• docs/implement.md

• docs/secrets.md

• docs/documentation.md

• docs/design.md

• tasks/todo.md

• tasks/lessons.md

• CLAUDE.md

• AGENTS.md

Profile rules:

• Baseline Conversion: prioritize accurate documentation of existing behavior.

• Upgrade Conversion: separate baseline-capture milestones from upgrade milestones; include migration/rollback notes when contracts change.

• Do not silently refactor implementation during conversion unless explicitly requested.

• In docs/implement.md , include 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 ).

5.5. Implementation Discipline (Mandatory)

Apply these rules to post-conversion implementation tasks:

• Use first-principles execution: solve the real root cause from requirements and architecture.

• Treat task and sub-task as the same execution unit.

• Enforce one task -> one atomic commit .

• Complete each task fully before commit, including impacted code/tests/config/scripts/docs.

• Follow code is cheap : if a module is problematic, delete and rewrite the module.

• Do not introduce compatibility code (adapter , shim , dual-path logic, deprecated aliases, temporary compatibility flags).

• If a rewrite changes interfaces, fix every impacted caller in the same task.

• Do not defer breakage fixes to future tasks.

6. Review Protocol

Before handoff:

• Agent 2 + Agent 3 review converted docs.

• Mandatory mcp__codex__codex review focused on docs-code alignment, missing edge cases, and milestone coverage.

• Apply findings and run exactly one Agent 2 + Agent 3 post-Codex re-review.

• Run one user annotation pass on docs/architecture.md

• docs/plans.md , resolve notes, and wait for explicit readiness confirmation.

If mcp__codex__codex is unavailable, pause and ask user to choose manual checklist path or alternate-model path.

7. Hooks Installation (Mandatory)

Install/update hooks after docs are accepted:

• 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

• Detect package manager by lockfile (bun.lock , pnpm-lock.yaml , yarn.lock , fallback npm).

• If no installer path exists, ask the user where their hook installer lives and stop.

• If command fails, surface error and stop for user resolution.

8. Final Handoff

Tell the user:

• Conversion/upgrade docs bootstrap is complete.

• Hooks are installed/updated in .claude/ and .codex/ .

• Baseline capture items vs upgrade backlog items.

• They should review docs/architecture.md

• docs/plans.md before implementation.

• Completion still depends on passing the final Production Readiness Gate.