Frenchie Method documentation

Quick start

Frenchie Method is installed with the same Frenchie package as Kit. Method text workflows do not need an API key. Kit file tools need login only when your agent processes files or generates assets.

npx @lab94/frenchie install

Restart your agent after install. Then choose the entry point that matches what you are doing:

For most new work, the first skill is /requirement. It creates the first durable artifact and gives every later step something concrete to depend on. If you want Method to initialize the feature folder and state.json before that, run /prepare-feature first.

After the requirement is clear, continue through the direct command path below:

/requirement      # tell your agent what you want; capture goals, constraints, and open questions
/qa-analysis     # turn the requirement into test cases before implementation planning
/design          # for user-facing work: define flows, states, copy, responsive behavior, and accessibility
/security-review # when risk is present: check auth, files, secrets, PII, billing, and abuse cases
/sa-analysis     # analyze architecture, data flow, APIs, migrations, rollback, and implementation risks
/task-plan       # convert the artifacts into ordered implementation tasks and file ownership
/implement       # make the code changes from fresh Method artifacts
/run-test        # run verification and write 06-test-report.md
/walkthrough     # inspect the result from the user's point of view
/pr-review       # review the actual change against the artifacts and quality bar
/fix-review      # if review finds issues, fix them and rerun the relevant checks
/release-check   # write 09-release-checklist.md; read-only readiness gate
/release         # only when the human explicitly approves release actions
/job-done        # close the workflow and decide whether to keep or clean up the worktree

Learn this direct path first. Use /method-check any time you are unsure what exists or what should happen next. Use /frenchie-method when you want the automatic task router to classify the task, check state, and recommend the next safe command. Method emits warnings on missing prereqs but never refuses to run a direct command.

npx @lab94/frenchie install --init-method

The optional init flag writes .frenchie/method.config.json and .frenchie/.gitignore. If the config is missing, Method continues with production-safe defaults.

Install flags

The installer auto-detects supported agents in the current project and writes only project-local config by default. Common flags:

Run npx @lab94/frenchie install --help for the authoritative list. Frenchie Method text workflows do not require an API key; --api-key only matters when you also want Kit file tools (OCR, transcription, extraction, image generation) to be ready without a separate npx @lab94/frenchie login step.

File architecture

Method writes state to disk. The agent reads command docs and templates from the installed skill, and writes project state and artifacts into .frenchie/ in the working repo — so any session, agent, or teammate can pick up the trail without replaying chat history.

.frenchie/
├── method.config.json          # optional project settings
├── .gitignore                  # Method-local ignores; Frenchie does not edit root .gitignore
├── templates/                  # optional custom artifact templates
└── docs/
    ├── knowledge/              # optional project knowledge notes
    └── feature/
        └── invite-only-workspaces/
            ├── state.json
            ├── 00-source-context.md
            ├── 01-requirement.md
            ├── 02-acceptance-criteria.md
            ├── 03-test-case.md
            ├── 04-implementation-plan.md
            ├── 05-design.md
            ├── 06-test-report.md
            ├── 07-walkthrough.md
            ├── 08-review-report.md
            ├── 09-release-checklist.md
            └── 10-postmortem.md

Built-in templates cover 00 through 10. These files are the stable artifact contracts; command output may still be summarized in chat, but artifact-bearing commands write or update their named file.

Example artifact

Artifacts are markdown prose with a small YAML frontmatter block — not YAML-only documents and not checklists. Here is a real-shape preview of 01-requirement.md:

---
artifactType: requirement
frenchieMethodVersion: 1
feature: invite-only-workspaces
stage: requirement
updatedAt: 2026-05-04T12:00:00.000Z
status: draft
---

# Invite-only workspaces

## Problem

Free-tier teams cannot self-serve a private workspace, so support
fields ~3 requests per week from people who started a trial in
the wrong workspace and want their data isolated.

## Users and scope

- In: any signed-in user can create a private workspace; invitees
  join via a one-time code.
- Out: SSO-backed workspaces, audit-log export, billing splits.

## Acceptance criteria

See `02-acceptance-criteria.md` (AC-001 through AC-104).

## Constraints

- No new top-level route — reuse `/settings/workspaces`.
- No new background jobs in this phase.

## Open questions

- Does invite expiry follow the existing magic-link TTL (15 min)
  or the longer org-invite TTL (7 days)?

Headings are not enforced — this shape comes from the built-in template at method/templates/01-requirement.md. Teams can ship custom templates by writing into .frenchie/templates/.

Settings

Method resolves .frenchie/method.config.json first. Invalid or missing values fall back to defaults after validation.

{
  "schemaVersion": 1,
  "artifactRoot": ".frenchie/docs/feature",
  "knowledgeRoot": ".frenchie/docs/knowledge",
  "templates": {
    "root": ".frenchie/templates",
    "fallbackToBuiltIn": true
  },
  "worktree": {
    "enabled": true,
    "root": "../",
    "pathPattern": "{repo}-{feature}",
    "branchPrefix": "feature/"
  },
  "release": {
    "enabled": true,
    "requireApproval": true
  },
  "review": {
    "crossModel": "off"
  },
  "strictness": {
    "orchestrator": "strict",
    "directSkills": "warn-and-continue"
  },
  "language": {
    "conversation": "auto",
    "artifacts": "auto"
  },
  "commands": {
    "preferPrefixedAliases": false
  },
  "skillTriggers": {}
}

Validation is conservative. Unknown or invalid values fall back to defaults, while invalid shapes are reported by /method-check and /frenchie-method.

State file

Each feature has a state.json. It tracks workflow state, artifact status, dependency hashes, decisions, and worktree metadata. It does not store full artifact bodies; the Markdown files remain the source of truth.

{
  "schemaVersion": 1,
  "feature": "invite-only-workspaces",
  "taskType": "new-feature",
  "taskSize": "medium",
  "currentStage": "qa-analysis",
  "artifactRoot": ".frenchie/docs/feature",
  "branch": "feature/invite-only-workspaces",
  "worktreePath": "../frenchie-invite-only-workspaces",
  "artifacts": {
    "01-requirement.md": {
      "status": "accepted",
      "bodyHash": "sha256-body-hash",
      "dependencies": []
    },
    "03-test-case.md": {
      "status": "ready",
      "bodyHash": "sha256-body-hash",
      "dependencies": [
        {
          "artifact": "01-requirement.md",
          "sourceHash": "sha256-body-hash"
        }
      ]
    }
  },
  "decisions": [
    {
      "at": "2026-05-02T10:00:00.000Z",
      "decision": "Continue after accepting stale UX copy",
      "reason": "User approved the narrower scope"
    }
  ]
}

Task types are new-feature, bug-fix, hotfix, documentation, spike, refactor, tech-debt, and dep-bump. Task sizes are xs, small, medium,large, and epic. Artifact status is missing, draft, ready, stale, or accepted.

Commands

Most direct commands also have a prefixed alias such as /frenchie-requirement or /frenchie-run-test. Exact slash-command availability depends on the agent. If slash commands are not exposed, ask the agent in natural language to use Frenchie Method, for example Frenchie Method requirement ....

Routed command families

Method recognizes PRD-style command names and routes them to the nearest production-depth command while preserving the invoked command name in the artifact note.

Routed commands also support prefixed aliases, for example /frenchie-api-design and /frenchie-changelog.

Workflow

Standard production work follows the full gate order below. Hotfixes may use shorter artifacts but keep state, review, verification, and release approval. Spikes may skip TDD gates, but must end in a promote/discard decision before /job-done.

/prepare-feature
→ /documenting-code when source context is missing
→ /requirement
→ /qa-analysis
→ /design when user-facing experience changes
→ /security-review when risk is present
→ /sa-analysis
→ /task-plan
→ /implement
→ /run-test
→ /walkthrough
→ /pr-review
→ /fix-review when needed
→ /release-check
→ /release only by explicit user invocation
→ /job-done

1. Requirement first. Capture the user goal, constraints, acceptance criteria, and open questions.
2. Design before build. Pick the route, components, data model, and interaction rules before editing code.
3. Test cases before implementation plan. Write what should be true, then plan the code.
4. Worktree isolation. Use a scoped workspace when the change is risky or parallelizable.
5. Walkthrough and review. Leave enough evidence for a human to audit the work without reconstructing it from chat.
6. Release remains explicit. /frenchie-method never runs /release automatically.

Orchestrator mode

After the basic command flow is clear, use /frenchie-method as the automatic task router. It does not replace the direct commands; it recommends which one should run next, and warns without blocking when prereqs are missing.

/frenchie-method "Add invite-only workspaces"

The orchestrator classifies the work as new-feature, bug-fix, hotfix, documentation, or spike; resolves config and feature state; checks stale artifacts, branch/worktree alignment, and missing gates; then recommends or executes the next safe Method command.

It stops for human approval before release, ambiguous PR creation, stale-artifact overrides, destructive cleanup, branch deletion, or accepted security risk. /release is never run automatically.

Artifacts

Method writes durable Markdown artifacts so the workflow survives context compaction, handoff, and review.

.frenchie/docs/feature/invite-only-workspaces/
├── state.json
├── 00-source-context.md
├── 01-requirement.md
├── 02-acceptance-criteria.md
├── 03-test-case.md
├── 04-implementation-plan.md
├── 05-design.md
├── 06-test-report.md
├── 07-walkthrough.md
├── 08-review-report.md
├── 09-release-checklist.md
└── 10-postmortem.md

The files are intentionally plain. Your agent can read them, update them, and cite them while implementing.

---
artifactType: test-case
frenchieMethodVersion: 1
feature: invite-only-workspaces
stage: qa-analysis
updatedAt: 2026-05-02T10:00:00.000Z
status: draft
---

# Test Cases

## Happy Paths
## Edge Cases
## Negative Cases
## Permission / Role Cases
## Validation Cases
## Automation Targets
## Expected Results

Built-in template validation checks required sections for 03-test-case.md, 04-implementation-plan.md, and 06-test-report.md. Custom templates can live under .frenchie/templates; when fallbackToBuiltIn is true, incomplete custom templates fall back to built-ins.

Freshness and gates

Method hashes artifact bodies, not frontmatter. Updating metadata such as updatedAt does not make dependents stale; changing the actual requirement, test case, or plan body does.

• 03-test-case.md comes before 04-implementation-plan.md.
• User-facing changes pass /design before implementation.
• High-risk changes pass /security-review.
• Implementation is followed by /run-test, /walkthrough, and /pr-review.
• /release-check must run before /release.
• /release and destructive cleanup require explicit human approval.

When stale artifacts are found, Method offers three choices: regenerate downstream artifacts, continue explicitly and record the decision, or stop so the user can edit artifacts. Stale decisions are recorded as blockers or warnings in 09-release-checklist.md; /release proceeds only after explicit user confirmation or accepted risk.

Using Kit inside Method

Method and Kit are separate layers. Method decides the workflow. Kit supplies file context when the workflow needs source material.

/ocr Project PRD.pdf
/frenchie-method use .frenchie/project-prd/result.md for the product launch workflow

Use Kit for OCR, transcription, extraction, and image generation. Use Method to turn those results into requirements, tests, plans, and review evidence.

For file setup, credits, and MCP transport details, read Kit Docs.

Worktrees

Method prefers isolated worktrees when the agent will make non-trivial changes. That keeps parallel attempts, review branches, and rollback paths clean.

git worktree add ../feature-invite-only -b codex/invite-only-workspaces

The worktree is not magic. It is a clean workspace boundary that makes the agent's changes easier to review and easier to throw away.

Review loop

Method is built around evidence, not confidence. Before a change is considered done, the agent should show the artifacts, tests, affected files, unresolved questions, and release risk.

• Requirement and design artifacts exist.
• Test cases match acceptance criteria.
• Implementation follows the plan or explains why it changed.
• Review output names risks and verification results.
• Release-check is informational until the user approves release actions.

FAQ

• Do I need an API key for Method?

  No. Method is a text workflow installed with the skill pack. Kit file processing needs login and credits.

• Is Method replacing tests or review?

  No. Method forces those things to appear earlier and be written down.

• Where should I start?

  Read the principles first, then use this page as the operating manual.