Methodology

AI-First Development Methodology

Purpose

The methodology keeps project and feature work understandable across sessions while making the process proportional to the task. Durable project facts live in Project Knowledge, an approved user-spec is the contract for a planned feature, execution skills own their domain workflows, and fresh reviewer agents diagnose completed work without taking decisions away from the orchestrator or the user.

Operating Model

Requests route directly to skills by intent. The global commands/ source is currently empty; feature planning, direct execution, initialization, documentation, and finalization do not depend on command wrapper files. Request the workflow in plain language; historical shorthand such as /new-user-spec or /done does not imply that an installed slash-command wrapper exists.

Choose the smallest path that fits the work:

One request may activate several skills. For example, a UI feature with state changes uses both layout-writing and code-writing; their verification and reviewers are coordinated in one execution rather than treated as unrelated pipelines.

Planned Feature Lifecycle

user-spec-planning → explicit approval → new task: implement the approved spec
→ verified implementation commit → documentation-writing feature finalization

Plan the Feature

user-spec-planning owns the complete planning contract:

1. Start or resume work/{feature}/logs/userspec/interview.yml. Ask 3–4 questions per batch and run as many batches as the actual gaps require; there is no fixed number of interview cycles.
2. Load the Project Knowledge router when it exists and follow only the routes relevant to the feature. Missing Project Knowledge does not block feature planning.
3. Once the intended outcome is clear enough, run code-researcher, write work/{feature}/code-research.md, and use code evidence in the remaining interview.
4. Run fresh interview-completeness-checker instances until the agreed scope has no substantive requirements gap. A finding that would expand the feature returns to the user for a decision.
5. Fill the bundled user-spec template in place. Keep its scaffold in English, write its content in the user's language, preserve the executor instruction, and commit the draft.
6. Validate every round in parallel with:
   • userspec-quality-validator for document quality, coverage, and testable criteria;
   • userspec-adequacy-validator for feasibility, proportionality, and architecture fit;
   • skeptic for factual claims about the current codebase.
7. Stop when all lanes are clean or after the third validation round. Obtain explicit user approval, set the spec and interview statuses, commit the approval, and return the absolute user-spec path for a new task.

If the request contains independently valuable outcomes, planning proposes a split and waits for the user's choice. Different files, code layers, or execution skills alone do not require separate specs.

Implement the Feature

The implementation task reads the approved user-spec.md, its executor instruction, decisions.md when present, and the relevant Project Knowledge routes. It then activates the skills required by the agreed work:

• code-writing owns application behavior, data flow, APIs, state, validation, and code changes;
• layout-writing owns markup, styling, typography, assets, responsive behavior, and visual evidence;
• infrastructure-setup owns Docker, hooks, CI/CD, delivery, release artifacts, monitoring, recovery, and other operational changes;
• prompt-master owns LLM prompt creation and revision;
• skill-master owns skill creation and revision.

Each executor reads context in proportion to the change, implements only agreed behavior, runs the smallest checks that establish the result, and coordinates every reviewer required by the active skills. When observable behavior changes, test-master selects the smallest reliable boundary that reproduces each meaningful risk; it does not create tests for artifacts with no contract to protect.

The user-spec template requires the verified implementation to be committed separately before feature finalization. decisions.md receives only material decisions or deviations that need to survive the current context.

Finalize the Feature

Feature finalization is an explicit mode of documentation-writing. The user identifies work/{feature}/ and asks to finish or finalize it; no wrapper command file is required.

The skill reads the spec, decisions, implementation, and relevant Git history; checks whether the feature is evidently complete; updates only affected durable Project Knowledge; removes active links that still treat the feature folder as current; moves it to work/completed/{feature}/; and commits the documentation and archive change. If Project Knowledge is missing, the documentation update is skipped but archival and finalization may still continue.

This is the only documentation mode that reads feature artifacts by default, archives a feature, or creates a finalization commit. A normal documentation update or audit does none of those.

Ad-hoc Work

A small direct request does not require a user-spec. The matching execution skill derives done from the request, reads only the needed project context, makes the focused change, and verifies it at the smallest useful boundary. Broader or cross-cutting work loads the contracts and Project Knowledge routes it actually affects.

A risk, idea, edge case, or improvement discovered during implementation or review is a proposal, not new authorization. The executor may correct a local defect required for the agreed result; a change to behavior, scope, approach, state, fallback, validation, or material complexity returns to the user for a decision.

New Projects and Project Knowledge

project-initialization creates a dual-runtime repository from its bundled template, preserves pre-existing files in the next available old* directory, configures Git hooks, creates the initialization commit, connects a private GitHub repository, creates main and dev, and leaves dev active. Reviewing or merging preserved old* files is separate work.

The next step is initial Project Knowledge through documentation-writing. Its adaptive interview derives what it can from the repository, uses as many question batches as needed, obtains checkpoint agreement for project definition, architecture, and operations/experience, proposes a documentation topology when one is not already established, and writes durable facts in English.

Project Knowledge lives in .claude/skills/project-knowledge/, whose SKILL.md is always the router. Use structure by context boundary rather than file size:

• compact projects may keep Project, Architecture, Patterns, Deployment, and applicable UX or domain facts in the router itself;
• standard projects use the router plus project.md, architecture.md, patterns.md, and deployment.md;
• ux-guidelines.md or domain references are added only when they form independently useful loading boundaries.

CLAUDE.md remains a compact entrypoint: project identity, Project Knowledge route, backlog path, and default branch. It does not duplicate detailed project facts.

Sources of Truth

Approved User Spec

work/{feature}/user-spec.md owns the agreed feature outcome, behavior, acceptance criteria, constraints, risks, accepted decisions, testing intent, and verification plan.

Project Knowledge

Project Knowledge owns current durable project facts: purpose, architecture, project-specific patterns and business rules, deployment and operations, and applicable UX or domain guidance. Code owns implementation detail; configuration or registries own changing inventories; work/ artifacts are evidence rather than owners of current project state.

Feature Folder

work/{feature}/
├── user-spec.md
├── code-research.md
├── decisions.md
└── logs/
    ├── userspec/
    │   └── interview.yml
    └── working/

Completed features move to work/completed/{feature}/. Planning templates, interview state, and the initializer script are bundled inside user-spec-planning; new-project templates are bundled inside project-initialization. There is no shared resource directory between skills.

Skill Responsibilities

A skill package owns its optional references/, deterministic scripts/, and output assets/. This keeps dependencies portable through Claude-to-Codex conversion and public publication instead of relying on unrelated global directories.

Review Model

Reusable methodology lives in skills. Dedicated reviewer agents add fresh isolated context, a bounded skeptical role, the minimum tools needed to inspect evidence, and a structured diagnostic result. They inherit the orchestrator's model without a caller override. They do not edit artifacts, design remediation, or decide whether work ships.

A finding is valid only when it establishes a concrete location, observed evidence, violated requirement, realistic triggering conditions, and impact. A clean result is valid. The orchestrator evaluates every result and may apply a correction only when that exact correction is inside the user request, approved plan, or user-spec.

Before the first review, the orchestrator selects the complete reviewer set required by all active skills. The set reviews the same revision in parallel as one wave; active skills do not create independent wave sequences. A correction that changes the reviewed result may trigger a fresh wave, subject to the owning workflow's limit. Implementation and writing workflows normally allow at most two waves; user-spec validation allows at most three rounds.

Common reviewer ownership is:

• every completed code implementation: code-reviewer;
• layout implementation: layout-reviewer with prepared source and rendered evidence;
• meaningful test-code changes: test-reviewer through test-master;
• changed security boundaries or an explicit security request: security-auditor;
• documentation edits: documentation-reviewer;
• material infrastructure work or an explicit infrastructure review: infrastructure-reviewer;
• prompt edits: prompt-reviewer;
• skill changes: the applicable skill-checker, skill-logic-reviewer, and skill-simplicity-reviewer lanes;

After the final permitted wave, the executor runs applicable direct checks and reports remaining findings or required scope decisions instead of starting an unbounded review loop.

Working Principles

• Simplest sufficient process: add a document, abstraction, rule, fallback, or coordination layer only for a current requirement or demonstrated failure.
• Proportional context: load the smallest context that preserves the affected contracts.
• One outcome, one user-facing specification: split only independently valuable outcomes and let the user decide.
• Evidence before action: reviewer identity or severity never substitutes for evidence, and a finding never expands authorization.
• Stable commits: commit meaningful states such as a draft spec, approved spec, verified implementation, or finalized documentation; do not force incidental state into a commit.

Claude and Codex Dual Runtime

Allowlisted Claude files are the source of truth; Codex files are generated runtime artifacts:

Claude source                                         Codex runtime
~/.claude/skills/**                                   ~/.codex/skills/**
~/.claude/agents/*.md                                 ~/.codex/agents/*.toml
~/.claude/commands/*.md, when present                 ~/.codex/skills/source-command-*/**
{project}/CLAUDE.md                                   {project}/AGENTS.md
{project}/.claude/{skills,agents,commands}/**          {project}/.codex/{skills,agents}/**

Markdown sources and references are adapted for the target runtime. Other bundled resources such as scripts, assets, images, and data are copied byte-for-byte, so bundled executables must remain runtime-neutral and resolve resources relative to their own package.

Conversion is manual. After changing an allowlisted global Claude source, run and review:

~/.claude/scripts/sync-to-codex.sh --apply

After changing a project-local Claude source, run and review:

~/.claude/scripts/sync-to-codex.sh --project "$PWD" --apply

Generated project AGENTS.md and .codex/** files are committed with their Claude sources, except host-local .codex/.sync/**. Global ~/.codex/** is runtime state outside the ~/.claude source repository and is not added to its commits. A reported conflict or validation error stops the workflow.

Approved deletions or renames may leave managed generated outputs. Inspect the reported orphan list and prune only when every target corresponds to the approved source change; do not use prune as a routine sync option.

MCP Import

MCP import is separate from skill conversion. The importer scans the global Claude MCP source and immediate projects under ~/projects; --project adds roots rather than narrowing that host-wide scope. Preview changes on every host whose Codex runtime must change:

~/.claude/scripts/sync-mcp-to-codex.sh

Review sources, servers, and warnings; stop on any warning or validation error. Then apply with --apply and inspect every changed Codex configuration. The dry run does not report deletions performed by --prune, so normal changes do not use it. Treat removal or relocation as a separate maintenance operation: inspect the import manifest and every target before an explicit prune. No scheduler performs either conversion, and credentials never belong in commits.