Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions .github/ISSUE_TEMPLATE/bug.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
name: Bug report
description: Report a Method defect or regression.
title: ""
labels:
- lane:inbox
Comment thread
flyingrobots marked this conversation as resolved.
- type:bug
body:
- type: textarea
id: observed
attributes:
label: Observed behavior
description: What happened?
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected behavior
description: What should have happened?
validations:
required: true
- type: textarea
id: reproduction
attributes:
label: Reproduction
description: Minimal commands, repo state, and inputs needed to reproduce.
placeholder: |
1. ...
2. ...
validations:
required: true
- type: textarea
id: impact
attributes:
label: Impact
description: Who is blocked or misled by this?
- type: textarea
id: acceptance
attributes:
label: Acceptance criteria
placeholder: |
- [ ] ...
validations:
required: true
- type: textarea
id: witness
attributes:
label: Witness plan
value: |
Expected evidence:
- failing test or reproduction:
- fix validation:
- retro:
5 changes: 5 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
blank_issues_enabled: false
contact_links:
- name: Method process overview
url: https://github.com/flyingrobots/method/blob/main/docs/PROCESS.md
about: Read the Method workflow before opening work.
45 changes: 45 additions & 0 deletions .github/ISSUE_TEMPLATE/spike.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
name: Method spike
description: Capture a temporary proof, learning cycle, or constraint probe.
title: ""
labels:
- lane:inbox
- type:spike
body:
- type: textarea
id: question
attributes:
label: Question
description: What are we trying to prove or learn?
validations:
required: true
- type: textarea
id: why-now
attributes:
label: Why now
description: What decision will this unblock?
validations:
required: true
- type: textarea
id: constraints
attributes:
label: Constraints
description: Stack, time, safety, or quality constraints.
placeholder: |
- ...
- type: textarea
id: evidence
attributes:
label: Expected evidence
description: What transcript, demo, test, or artifact proves the learning?
placeholder: |
- [ ] ...
validations:
required: true
- type: textarea
id: closeout
attributes:
label: Adopt, adapt, or retire decision
description: Fill this in during closeout.
value: |
Decision:
Follow-up:
94 changes: 94 additions & 0 deletions .github/ISSUE_TEMPLATE/work-item.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
name: Method work item
description: Propose shaped Method work with a hill, scope, and witness plan.
title: ""
labels:
- lane:inbox
- type:enhancement
body:
- type: markdown
attributes:
value: |
Use a short, branch-safe title. Active work uses a branch slug derived from this title.
Labels are canonical tracker metadata. If you want a lane or legend other than inbox triage,
request it below; a maintainer or agent must apply the actual label.
- type: textarea
id: requested-classification
attributes:
label: Requested classification
description: Optional triage request. This does not set canonical labels.
placeholder: |
Suggested lane:
Suggested legend:
- type: textarea
id: hill
attributes:
label: Hill
description: Name the user value in Method/IBM Design Thinking style.
placeholder: As a contributor, I want ..., so that ...
validations:
required: true
- type: textarea
id: sponsored-perspectives
attributes:
label: Sponsored perspectives
description: Name abstract human and agent seats, not literal people or model brands.
value: |
Human:
Agent:
validations:
required: true
- type: textarea
id: context
attributes:
label: Context
description: What repo truth, user need, or defect motivates this work?
validations:
required: true
- type: textarea
id: scope
attributes:
label: Scope
description: What is in bounds?
placeholder: |
- ...
validations:
required: true
- type: textarea
id: out-of-scope
attributes:
label: Out of scope
description: What should not be solved in this issue?
placeholder: |
- ...
- type: textarea
id: acceptance
attributes:
label: Acceptance criteria
description: Concrete checks that prove the issue is complete.
placeholder: |
- [ ] ...
validations:
required: true
- type: textarea
id: witness
attributes:
label: Witness plan
description: Expected evidence for tests, playback, docs, and retro.
value: |
Expected evidence:
- tests:
- playback:
- docs:
- retro:
validations:
required: true
- type: textarea
id: method-artifacts
attributes:
label: Method artifacts
description: Fill these links as the work proceeds.
value: |
Design:
Witness:
Retro:
PR:
22 changes: 22 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# Pull Request

## Linked issue

Closes #

## Branch / issue-title check

- [ ] Branch name is the linked issue title slug, or the exception is explained here.

## Method evidence

- [ ] Design doc linked or not required.
- [ ] Tests or validation evidence included.
- [ ] Playback/witness included or not required.
- [ ] Retro included or not required.

## Tracker hygiene

- [ ] Linked issue had `work-in-progress` while active.
- [ ] Linked issue lane/status labels are current.
- [ ] Follow-up work is captured as GitHub Issues, not hidden in chat or local-only backlog files.
3 changes: 2 additions & 1 deletion ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ Two-way sync between the local backlog and GitHub Issues:
## Testing

<!-- generate:test-summary -->
22 test files in `tests/` using Vitest:
23 test files in `tests/` using Vitest:

- `api.test.ts`
- `build.test.ts`
Expand All @@ -127,6 +127,7 @@ Two-way sync between the local backlog and GitHub Issues:
- `github-adapter.test.ts`
- `lane-contract.test.ts`
- `mcp.test.ts`
- `migrate-backlog-to-github-issues.test.ts`
- `package.test.ts`
- `repo-discipline.test.ts`
- `review-state-exec.test.ts`
Expand Down
18 changes: 11 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,17 @@ npm test

## Making Changes

1. **Check the backlog.** Run `method status` to see what is in
`inbox/`, `asap/`, `up-next/`, and `cool-ideas/`.
2. **Open an issue** if you want to propose new work or discuss an
existing backlog item before starting.
3. **Create a cycle branch** from `main`: `cycles/####-slug`.
4. **Follow the loop.** Design, RED, GREEN, playback, close, PR.
5. **Open a pull request** against `main` with the full cycle packet
1. **Start from GitHub Issues.** Work is tracked in repo-local GitHub
Issues, not local backlog files. Use Method lane labels such as
`lane:inbox`, `lane:asap`, `lane:bad-code`, and `lane:cool-ideas`.
2. **Normalize the issue title before starting.** Issue titles should be
short, branch-safe, and contributor-readable.
3. **Mark active work.** Add `work-in-progress` when you start so other
contributors and agents know the issue is claimed.
4. **Create a branch from the issue title slug** from `main`, for
example `foo-feature-needs-external-bar-integration`.
5. **Follow the loop.** Design, RED, GREEN, playback, close, PR.
6. **Open a pull request** against `main` with the full Method evidence
(design doc, tests, implementation, retro, witness).

## Code Style
Expand Down
39 changes: 23 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
# METHOD

A backlog, a loop, and honest bookkeeping.
Issues, a loop, and honest bookkeeping.

## What is METHOD?

METHOD is a lightweight process framework for software projects where
humans and agents collaborate. It provides:

- A **backlog** organized by lanes (inbox, asap, bad-code, cool-ideas)
- **GitHub Issues** organized by Method labels (`lane:inbox`,
`lane:asap`, `lane:bad-code`, `lane:cool-ideas`, release milestones)
- A **cycle loop** (pull → design → test → playback → close → review → ship)
- **Honest bookkeeping** through design docs, retros, witnesses, and drift detection

Expand All @@ -27,20 +28,20 @@ npm install @flyingrobots/method
method init .

# Capture an idea
method inbox "Add dark mode support" --legend PROCESS
gh issue create --title "Add dark mode support" --label lane:inbox

# Check workspace health
method doctor

# See what's in the backlog
method status
# Pick work from GitHub Issues
gh issue list --label lane:asap
```

## Documentation

| Document | What it covers |
|----------|---------------|
| [`docs/PROCESS.md`](docs/PROCESS.md) | Cycle doctrine — how work flows from backlog to shipped |
| [`docs/PROCESS.md`](docs/PROCESS.md) | Cycle doctrine — how work flows from issue to shipped |
| [`docs/RELEASE.md`](docs/RELEASE.md) | Release doctrine and runbook |
| [`docs/GUIDE.md`](docs/GUIDE.md) | Operator advice and getting started |
| [`docs/CLI.md`](docs/CLI.md) | CLI command reference |
Expand All @@ -51,8 +52,14 @@ method status

## Principles

**The filesystem is the database.** A directory is a priority. A
filename is an identity. Moving a file is a decision. `ls` is the query.
**GitHub Issues are the live work tracker.** A label is a lane. A
milestone is release scope. `work-in-progress` means someone is actively
working the issue. This keeps METHOD legible to ordinary open-source
contributors.

**The repository is the evidence ledger.** Design docs, tests, playback
witnesses, retros, release notes, and generated signposts stay in the
repo because they are durable evidence, not ephemeral tracker state.

**Tests are the executable spec.** Design names the hill and the
playback questions. Tests prove the answers.
Expand All @@ -61,7 +68,7 @@ playback questions. Tests prove the answers.
are rerunnable proof, not victory photos.

**Process should be calm.** No sprints. No velocity. No burndown. A
backlog tiered by judgment, and a loop for doing it well.
small issue taxonomy, clear evidence, and a loop for doing work well.

**The METHOD repo gets no special pleading.** This repository uses
METHOD on itself. If repo truth conflicts with doctrine, repair the
Expand All @@ -83,20 +90,20 @@ docs/
releases/
vX.Y.Z.md user-facing release notes
method/
backlog/
inbox/ raw ideas
asap/ pull next
cool-ideas/ experiments
bad-code/ tech debt
backlog/ legacy/migration-only backlog cards
legends/ named domains
retro/<cycle>/ retrospectives + witnesses
graveyard/ retired work
graveyard/ legacy retired work
.github/
ISSUE_TEMPLATE/ GitHub issue forms for Method work
pull_request_template.md PR evidence checklist
```

## The loop

```text
idea → inbox → lane → design doc → RED → GREEN → playback → retro
GitHub issue → lane label → branch → design doc → RED → GREEN
→ playback → retro
→ PR/review → main → ship sync
```

Expand Down
Loading
Loading