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.