PROCESS.md

Process

METHOD cycles run as a calm pull-design-test-playback-close-review-ship-sync loop.

Rules

• GitHub Issues are the live work tracker. Repository files are the evidence ledger.
• Pulling work is commitment. The issue is marked work-in-progress and does not silently fall back into the queue.
• Playback questions drive the design and the tests.
• Playback verification requires the matching perspective: Human playback questions must be verified by a human operator, and Agent playback questions must be verified by an agent. Neither seat can unilaterally sign off on the other's hill.
• Designs must name their accessibility/assistive posture, localization/directionality posture, and agent inspectability posture explicitly, even if the answer is "not in scope."
• If a claimed result cannot be reproduced, it is not done.
• Drift is checked explicitly at close, not hand-waved after the fact. Invariant preservation is part of the drift check.
• This repo must pass method doctor with zero issues before any release. METHOD must be an example of the correct application of what it preaches.
• All cycle witnesses included in a release must be re-executed and green at the release commit. A witness from a prior commit is stale evidence.
• Human playback questions require explicit human sign-off before release. An agent cannot unilaterally confirm a human hill. The release runbook must include a human-in-the-loop confirmation step where a human operator attests that each human hill holds true.
• human, agent, and user are abstract seats or perspectives in METHOD doctrine, not literal people, accounts, or model brands.
• Issue maintenance happens at cycle boundaries, not continuously.
• All raw intake, including feedback or review notes, lands in GitHub Issues with lane:inbox. Use the issue body and comments for provenance when origin or timing matters.
• Repo-level ship surfaces such as BEARING.md and CHANGELOG.md reflect merged main state, not branch-local closeout state.
• If merged main is ever found carrying an open cycle packet, treat that as repo-truth drift. Stop, close or repair the packet, and only then continue release or ship work.
• Review visibility is available through method review-state, which summarizes branch and PR context without turning METHOD into a forge cockpit.
• All cycle work must be done on a branch named from the linked issue title slug, for example foo-feature-needs-external-bar-integration.
• Once a full cycle is complete (after the retro), the operator must push the branch and open a PR to the target branch (usually main).
• Agents must stage and commit all modified files at the end of each turn to maintain a transparent and recoverable session history.

Default Loop

1. Pull a GitHub issue into docs/design/<cycle>.md or, for release-tagged work, into docs/releases/<version>/design/<cycle>.md. Add work-in-progress to the issue and link the issue from the design doc frontmatter.
2. Write the design with both human and agent sponsors named as abstract roles (e.g., "System Architect", "Workflow Automator"), plus the accessibility, localization, and agent-inspectability contract. Treat user the same way: it names the served perspective in the hill or witness, like a user story, not a literal named person.
3. Write failing tests from the playback questions.
4. Make the tests pass.
5. Produce a reproducible playback witness, including reduced/ linearized, localized, or agent-facing paths when the hill claims them. A purely observational artifact may support the witness, but it does not satisfy done on its own. The witness must include executable verification instructions and sandbox setup steps so a reviewer can reproduce the verification independently.
6. Close the cycle packet with a retro in either docs/method/retro/<cycle>/<cycle>.md or docs/releases/<version>/retros/<cycle>/<cycle>.md, depending on whether the cycle carries release scope.
7. Review the complete cycle packet on a branch or PR.
8. After merge, update repo-level ship surfaces on main such as BEARING.md, CHANGELOG.md, and release notes when relevant.

Release prep and ship sync are never excuses to leave an already-merged cycle packet open on main. If that state is discovered, stop and repair it before continuing.

Workflow

METHOD remains forge-agnostic in doctrine: it uses Git for distributed coordination. GitHub Issues are the default live tracker for work in this implementation.

Branch Naming

• Cycle Branches: Use the linked issue title slug (e.g., foo-feature-needs-external-bar-integration).
• Maintenance Branches: Use maint-slug for low-risk changes that require review (e.g., maint-fix-typos).
• Triage: Small label, title, or issue-body cleanup can happen in GitHub without a branch when no repo files change.

Issue titles are workflow identity. Before work starts, keep titles short, branch-safe, and readable. Avoid legend prefixes, issue numbers, and vague titles.

The Cycle Lifecycle

1. Pull: Pull the GitHub issue.
2. Branch: Create a branch from the latest main using the issue title slug.
3. Execute: Perform the loop (design, tests, act, playback).
4. Close: Run method close to write the retro and witness metadata.
5. Merge: Open a PR/Review. Once approved, merge to main.

Intake and Triage

1. Capture: Store raw review notes, critique, or outside-in observations as GitHub Issues with lane:inbox.
2. Annotate when useful: Record provenance in the issue body or comments when the origin or timing matters.
3. Process: During a maintenance pass, convert the inbox item into a durable choice: lane:asap, lane:bad-code, lane:cool-ideas, lane:release plus a milestone, a direct docs repair, or closure with a disposition comment.
4. Do not split intake systems: GitHub Issues are the raw intake path. Avoid parallel holding areas for critique or review notes.

Legacy filesystem backlog commands and docs/method/backlog/** remain compatibility and migration surfaces until repo-local migrations are complete. They are not the new authority model.

The Ship Sync Maneuver

After a cycle branch is merged to main, the operator (human or agent) must perform a Ship Sync to update the repo's public signposts:

1. Sync: Pull the merged main local machine.
2. Update BEARING: Refresh docs/BEARING.md to reflect the current priority and recent ships.
3. Update CHANGELOG: Add the changes to CHANGELOG.md.
4. Refresh VISION: If significant, run the Executive Summary Protocol to refresh docs/VISION.md.
5. Commit: Push these updates directly to main.

If Ship Sync discovers an open cycle packet already sitting on main, that is a stop condition. Close or repair the packet first, then resume repo-level signpost work.

System-Style JavaScript

METHOD adopts the "System-Style JavaScript" standard to ensure architectural integrity and runtime authority.

Core Principles

• Runtime Truth: Boundary data must be validated at runtime. Use Zod schemas in src/domain.ts to define the system's "Domain Forms."
• Hexagonal Architecture: Keep the core domain logic (in src/index.ts) clean and separate from presentation adapters (CLI) and infrastructure (filesystem, GitHub API).
• Browser-First Portability: The core domain logic should avoid Node-specific APIs. Use adapters to bridge to Node or Web environments.
• Lint is Law: Strict linting and formatting are enforced to reduce meaningless diff noise and ensure consistent style.
• Honest Design: Don't use "just-in-case" abstractions. Abstractions must buy their way into the repo by proving they reduce complexity or enforce an invariant.

Special Cycles

Executive Summary Protocol

A specialized cycle for "reading the repo and summarizing what it is." This protocol ensures that generated signposts like docs/VISION.md are reproducible and grounded in artifact history.

Phase 1: Inventory

1. Enumerate governing surfaces in precedence order:
   • README.md
   • repo instructions and docs/PROCESS.md
   • docs/method/legends/*.md
   • docs/design/*.md
   • docs/method/retro/*/
   • backlog lanes in repo-defined order
   • docs/method/graveyard/
2. Record the exact source list that will ground the synthesis.

Phase 2: Read and Synthesize

1. Read the inventoried surfaces in order and extract:
   • repo identity and doctrine
   • current state and completed cycles
   • signposts and their roles
   • legends and active domain load
   • roadmap by lane
   • open questions and current limits
2. Generate a bounded signpost with required sections:
   • Identity
   • Current state
   • Signposts
   • Legends
   • Roadmap
   • Open questions
   • Limits
3. Keep this phase read-only. Taxonomy changes, backlog edits, or new legends are follow-up work, not part of synthesis itself.

Phase 3: Generate Witness

1. Capture provenance fields for the generated signpost:
   • generation timestamp
   • repo commit SHA
   • source manifest
   • witness reference
   • declared provenance level
2. Store the full session witness outside the signpost body and link to it from the signpost metadata.
3. Make every repo-state claim traceable either to a cited source file or to the linked verification witness.

Phase 4: Verification

1. Run repo tests that validate signpost structure and provenance.
2. Run method status so the summary can be checked against the repo's current visible state.
3. If the synthesis triggers follow-up maintenance ideas, record them as separate backlog items after the read-only summary is complete.

Behavior Spikes

A specialized cycle for temporary implementations that exist to prove behavior, buy clarity, or surface stack constraints.

Phase 1: Capture

1. Record the goal, stack constraints, and the "why" in a backlog item.
2. Explicitly tag the item as a SPIKE (e.g., SPIKE_my-experiment).

Phase 2: Execute

1. Build the minimum implementation necessary to prove the behavior.
2. Don't worry about production-grade hardening, but keep the core honest.

Phase 3: Witness

1. Produce a playback witness (transcript, demo, test results) that proves the behavior was achieved or the constraint was identified.
2. Close the cycle with a retro explaining what was learned and whether the approach should be adopted, adapted, or retired.

Phase 4: Retire

1. Honestly discard or replace the implementation.
2. If retired, move artifacts to docs/method/graveyard/.
3. If adopted, replace the spike with a formal design cycle.

Design Constraints

Meaning must survive without decoration. If the work only makes sense with color, layout, motion, or shared visual context, the design is unfinished. Rich interaction is valuable, but the underlying truth must stand on its own.

Accessibility is a product concern, not a fallback string path. Designs must name the linear reading model and reduced-complexity experience, not assume the default operator.

Localization is not translation after the fact. Wording, wrapping, formatting, and directionality are design constraints from the start. Prefer logical start/end thinking over hardcoded left/right assumptions.

Coordination

METHOD is designed for a solo developer working with an agent. It scales to a team without adding meetings, roles, or synchronization ceremonies. The mechanism is passive legibility.

If you can answer these questions by reading the repo, you do not need a standup:

• What is actively open? → GitHub Issues by Method lane label
• Is this workspace healthy? → method doctor
• What is under review? → method review-state
• What is committed? → each design doc names its sponsors and hill
• What is next? → lane:asap issues without work-in-progress
• What failed and why? → ls docs/method/retro/
• What did we decide not to do? → closed GitHub Issues with disposition comments, plus legacy docs/method/graveyard/ during migration

No standups. No syncs. No status emails. No sprint planning. No retro meetings. The retro is a document, not a ceremony. The repo is the single source of truth. Read it.