# Methodology

> Explains the current AI-First development methodology: skill routing, Project Knowledge, user-spec planning and execution, evidence-gated reviews, feature finalization, and the Claude/Codex dual runtime. Use when: "изучи методологию", "как работает пайплайн", "как делать фичи", "как устроены скиллы", "how does the methodology work", "explain the workflow"

- Skill: `pavel-molyanov/methodology` (Agent Skill)
- Install (CLI): `npx skillmds@latest add pavel-molyanov/methodology`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pavel-molyanov/methodology/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: pavel-molyanov (https://skillmd.com/u/pavel-molyanov)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/pavel-molyanov/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:

| Need | Path |
|---|---|
| Small, well-defined change | Invoke the matching execution skill directly |
| Feature whose behavior or approach needs agreement | `user-spec-planning` → approval → execution → finalization |
| New repository | `project-initialization` → initial Project Knowledge → feature or ad-hoc work |
| Documentation-only work | `documentation-writing` with the evidence boundary named by the request |
| Review or audit only | Use the matching review skill or reviewer without modifying the artifact |

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

```text
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

```text
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

| Area | Owning skills |
|---|---|
| Feature requirements | `user-spec-planning` |
| Project documentation and finalization | `documentation-writing` |
| Application implementation | `code-writing` |
| UI implementation and visual evidence | `layout-writing` |
| Infrastructure and operations | `infrastructure-setup` |
| Project creation | `project-initialization` |
| Prompt authoring | `prompt-master` |
| Skill authoring | `skill-master` |
| Test selection and quality | `test-master` |
| Code, layout, and security review criteria | `code-reviewing`, `layout-reviewing`, `security-auditor` |

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:

```text
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:

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

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

```bash
~/.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:

```bash
~/.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.