@pixelfactoryio/theway 0.0.0-stage → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,35 @@
1
1
  {
2
2
  "name": "@pixelfactoryio/theway",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.4.0",
4
+ "description": "A spec-first workflow for Claude Code",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/pixelfactoryio/theway.git"
9
+ },
10
+ "type": "module",
11
+ "bin": {
12
+ "theway": "dist/theway.js"
13
+ },
14
+ "engines": {
15
+ "node": ">=22.12.0"
16
+ },
17
+ "packageManager": "bun@1.3.14",
18
+ "publishConfig": {
19
+ "access": "public"
20
+ },
21
+ "files": [
22
+ "dist",
23
+ "plugin"
24
+ ],
25
+ "scripts": {
26
+ "build": "bun build src/cli.ts --target=node --outfile dist/theway.js",
27
+ "typecheck": "tsc --noEmit -p .",
28
+ "test": "bun test"
29
+ },
30
+ "devDependencies": {
31
+ "typescript": "^5",
32
+ "@types/node": "^22",
33
+ "commander": "15.0.0"
34
+ }
35
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "name": "theway",
3
+ "version": "0.4.0",
4
+ "description": "theway writes a spec and a numbered task list before any code, then implements the tasks in your session or through agents that open a reviewed, CI-green pull request.",
5
+ "author": {
6
+ "name": "Amine",
7
+ "email": "amine@pixelfactory.io"
8
+ }
9
+ }
@@ -0,0 +1,89 @@
1
+ ---
2
+ description: Move a finished change to changes/archive/ under a dated folder
3
+ author: Amine
4
+ allowed-tools: Bash(theway:*)
5
+ ---
6
+
7
+ # TheWay: Archive Spec
8
+
9
+ Archive a completed spec by moving it to the archive folder with a timestamp.
10
+
11
+ ## Locate the home
12
+
13
+ Run `theway path` and use the folder it prints as `<home>`: TheWay files are stored in `<home>/<project>/`, where `<project>` is your project directory name. Take `<home>` only from `theway path`, never from a path written in `config.yaml` or elsewhere.
14
+ - If `theway` is not found, tell the user to add the folder theway is installed in (`~/.local/bin` by default) to their `PATH`, or to run `/theway:setup`, and stop.
15
+ - If it fails with `error: unknown command 'path'`, the installed `theway` is older than these commands: tell the user to run `/theway:setup` and stop.
16
+ - Do not check for files under `<home>` before reading them. If reading `<home>/config.yaml` or a file under `<home>/data/` or `<home>/templates/` fails because it does not exist, theway is not set up: tell the user to run `/theway:setup` and stop.
17
+
18
+ ## Usage
19
+
20
+ This command archives a completed change after it has been:
21
+ - Fully implemented
22
+ - Tested and validated
23
+ - Deployed to production (if applicable)
24
+ - Confirmed working
25
+
26
+ ## Steps
27
+
28
+ > Follow the conventions in `<home>/data/standards/interaction.md` (exploration and reporting).
29
+
30
+ ### 1. Require an Explicit Instruction (STOP gate)
31
+
32
+ **Do NOT archive off an implicit signal** ("it's merged", "it's done", "ship it"). Archiving is destructive (moves the folder) and must be requested explicitly: the user must name the change and explicitly say to archive it. If the change-id is missing or you're inferring intent, stop and ask. A reply that explicitly says to archive `<change-id>` after a stop is the confirmation: go on to Step 2.
33
+
34
+ ### 2. Verify Completion
35
+
36
+ Run `list` and show the task count before archiving:
37
+
38
+ ```bash
39
+ theway list <project>
40
+ ```
41
+
42
+ - If the change is not at `N/N tasks done`, surface which numbered tasks are open and ask the user to fix them or confirm an override. Do not proceed on your own.
43
+ - `archive` enforces this too: it refuses unless every numbered task in `tasks.md` is ticked; other checkboxes are not tasks (use `--force` only when the user explicitly accepts stale/N-A tasks).
44
+
45
+ ### 3. Move to Archive
46
+
47
+ ```bash
48
+ theway archive <project> <change-id>
49
+ # only if the user explicitly accepts remaining open numbered tasks:
50
+ theway archive <project> <change-id> --force
51
+ ```
52
+
53
+ ### 4. Update Project Documentation (if needed)
54
+
55
+ - Update architecture docs in `docs/` with any new patterns or conventions
56
+ - Clean up any temporary notes
57
+
58
+ ### 5. Confirm Archive
59
+
60
+ - Verify folder moved successfully
61
+ - Confirm archive location: the `Archived: <path>` line, `<home>/<project>/changes/archive/YYYY-MM-DD-[change-id]/`
62
+
63
+ ## Archive Structure
64
+
65
+ Archived changes are stored with timestamps:
66
+ ```
67
+ <home>/<project>/changes/archive/
68
+ ├── 2025-10-01-implement-api-gateway/
69
+ ├── 2025-10-10-add-logging-framework/
70
+ └── 2025-10-15-update-auth-middleware/
71
+ ```
72
+
73
+ ## What Gets Archived
74
+
75
+ The entire change folder including:
76
+ - `spec.md` - The spec analysis with proposal and hardpoints
77
+ - `tasks.md` - Completed task list (all checked)
78
+ - `design.md` - Technical design (if present)
79
+ - Any other files in the change folder
80
+
81
+ ## Historical Record
82
+
83
+ Archives serve as:
84
+ - Historical record of decisions
85
+ - Reference for similar future changes
86
+ - Audit trail of what was done and why
87
+ - Learning resource for the team
88
+
89
+ ---
@@ -0,0 +1,106 @@
1
+ ---
2
+ description: Implement changes through agents that open a PR, then review it and drive CI to green
3
+ author: Amine
4
+ allowed-tools: Bash(theway:*)
5
+ ---
6
+
7
+ # TheWay: Develop Workflow Mode
8
+
9
+ You are now in **Develop Workflow Mode** - developing changes through orchestrated agents instead of implementing inline.
10
+
11
+ ## Locate the home
12
+
13
+ Run `theway path` and use the folder it prints as `<home>`: TheWay files are stored in `<home>/<project>/`, where `<project>` is your project directory name. Take `<home>` only from `theway path`, never from a path written in `config.yaml` or elsewhere.
14
+ - If `theway` is not found, tell the user to add the folder theway is installed in (`~/.local/bin` by default) to their `PATH`, or to run `/theway:setup`, and stop.
15
+ - If it fails with `error: unknown command 'path'`, the installed `theway` is older than these commands: tell the user to run `/theway:setup` and stop.
16
+ - Do not check for files under `<home>` before reading them. If reading `<home>/config.yaml` or a file under `<home>/data/` or `<home>/templates/` fails because it does not exist, theway is not set up: tell the user to run `/theway:setup` and stop.
17
+
18
+ ## Invocation
19
+
20
+ ```
21
+ /theway:develop-workflow <change-id> [<change-id> ...]
22
+ ```
23
+
24
+ - **One change ID:** develop the change and stop when its PR is ready for validation. Never merge it.
25
+ - **Multiple change IDs (series):** develop each change strictly in the given order. Merging is implied: each change's PR must be merged before the next change starts, since later changes build on earlier ones.
26
+
27
+ **Authorization boundary:** invoking this command authorizes pushing branches, opening PRs, and merging exactly as the syntax above grants — nothing more. This invocation is also the explicit opt-in for the Workflow tool. Do not ask for permission mid-run for actions the syntax already grants; do not perform outward actions it doesn't.
28
+
29
+ ## Workflow Steps
30
+
31
+ > Follow the conventions in `<home>/data/standards/interaction.md` (exploration and reporting).
32
+
33
+ Run Steps 1-6 as a loop, once per change ID, in order.
34
+
35
+ ### Step 1: Load Context
36
+
37
+ Run `theway path <project> <change-id>` and use the folder it prints as `<change-dir>` for this change. Then read these exact paths directly — do not search the filesystem to locate them:
38
+ - `<home>/config.yaml` - Global config and conventions
39
+ - `<home>/data/standards/develop.md` - How a change is implemented and verified (given to every implementer)
40
+ - `<change-dir>/spec.md` - Why, what, risks and Success Criteria
41
+ - `<change-dir>/tasks.md` - The work, as numbered tasks
42
+ - `<change-dir>/design.md` - Technical specs (if present)
43
+ - `docs/architecture/coding-standards.md` - Project coding standards (if exists)
44
+
45
+ From `<home>/config.yaml`, take `workflow.review_rounds` (review rounds per change, default 1) and `workflow.ci_attempts` (CI attempts per change, default 2). A key that is absent or not a non-negative integer (`ci_attempts`: a positive integer) takes its default.
46
+
47
+ Also take the agent models from `workflow.models`: `implementer` (default `opus`), `reviewer` (default `opus`), `fix` (default `opus`) and `ci` (default `sonnet`). Each must be `opus` or `sonnet`; a key that is absent or holds any other value takes its default.
48
+
49
+ ### Step 2: Branch
50
+
51
+ Sync the main branch, then create (or check out) the change's feature branch from it.
52
+
53
+ ### Step 3: Implement via Orchestrated Agents
54
+
55
+ Orchestrate with the **Workflow tool**. If it is unavailable in this session, fall back to Agent-tool fan-out with the same stage structure.
56
+
57
+ **Model policy** (applies to every agent spawned in Steps 3-5, Workflow `agent()` and Agent-tool fallback alike):
58
+ - Implementers: `workflow.models.implementer`. When it is `opus`, `sonnet` is acceptable for implementers on mechanical tasks.
59
+ - Adversarial reviewers and the fix check: `workflow.models.reviewer`.
60
+ - Fix agents: `workflow.models.fix`.
61
+ - CI polling and log-fetch agents: `workflow.models.ci`.
62
+ - Never `haiku`. Always set `model` explicitly — do not rely on inheriting the session model.
63
+
64
+ **Implementers.** One implementer per change by default: the tasks of a change usually build on each other and touch the same files, so splitting them adds handoffs and merges without saving time. Split into parallel agents, each in its own worktree, only for large parts that are independent and touch different files; chain dependent parts, never run them in parallel. Each implementer gets `<home>/data/standards/develop.md`, the change's `<change-dir>/spec.md`, `<change-dir>/tasks.md` and `<change-dir>/design.md`, and its part of the work. When the spec does not fit the code, it stops and returns a blocker (what it found, the options) instead of redesigning. It commits locally on the feature branch with Conventional Commits (`type(scope): description`, imperative, lowercase), verifies its work as the standard says (including the CI's commands that can run locally), then pushes the branch and opens the PR (Step 4) and returns the PR URL, its verification and any blocker. The orchestrator — not the agents — checks off completed tasks in `<change-dir>/tasks.md` and records discoveries in its Notes section.
65
+
66
+ ### Step 4: Open PR
67
+
68
+ The implementer opens the PR with `gh pr create`; the orchestrator only collects its URL.
69
+
70
+ - Commit and PR text describe only what the change does — never the process or tooling that produced it.
71
+ - Keep the PR body minimal: one-line subject, bullets only when the change isn't self-evident.
72
+
73
+ ### Step 5: Review and CI
74
+
75
+ Once the PR is open, run up to `review_rounds` review rounds while CI runs. With `review_rounds: 0`, skip the reviewers, the triage and the fix check: only CI runs, and the round below reduces to its CI part.
76
+
77
+ Each round:
78
+
79
+ 1. **Review while CI runs.** Start the reviewers and the CI polling together, on the PR's current head.
80
+ - Spawn independent reviewer agents prompted to refute or break the PR diff: against `spec.md` (each Success Criterion met, nothing outside Scope, nothing it lists as Out of Scope), and for correctness, edge cases and convention violations. A correct diff that does something the spec did not ask for is a finding. Each finding's `file` is a path relative to the repository root, without a leading `./`.
81
+ - Poll the PR checks.
82
+ 2. **Triage findings**, once per round:
83
+ 1. Number the round's findings `0..N-1` in the order reported and verify each one. Each gets one verdict: `confirmed` (real), `false_positive` (refuted), `duplicate` (the same problem as an earlier finding of the round, which it names), `nit` (real, cosmetic) or `out_of_scope` (not this PR's).
84
+ 2. Only `confirmed` findings go to the fix agent. List the `false_positive`, `nit` and `out_of_scope` findings (index, verdict, title) in the Exit report.
85
+ 3. **Triage CI.** On a failed run, fetch the log (`gh run view <run-id> --log-failed`, then the full `--log` if that is empty) and quote the real error line before attempting any fix; never diagnose from memory or plausibility. Classify the failure as `code_bug`, `test_failure`, `lint_format`, `typecheck`, `dependency_install`, `flaky_infra`, `base_branch_red` or `unknown`. A failure of this PR (any class but `flaky_infra` and `base_branch_red`) goes to the fix agent; `flaky_infra` and `base_branch_red` follow the not-this-PR path below.
86
+ - **Not this PR's failure** (base branch red or flaky infra): when the base branch is red, port its fix onto the branch if one exists there, otherwise report it; then re-run the failed jobs once (`gh run rerun <run-id> --failed`).
87
+ 4. **Fix once.** When the round has confirmed findings or CI failed for this PR, spawn one fix agent with both: the confirmed findings and the quoted CI error. It commits the fixes on the branch and pushes once.
88
+ 5. **Fix check** (skipped with `review_rounds: 0`), on that push while CI reruns: spawn one agent that reads the fix commits (`git log` / `git diff` from the round's reviewed head to the new head) and the round's confirmed findings, and answers, per finding, `resolved` or `not resolved` with a one-line reason. It does not look for new problems. Any `not resolved` finding fails the change (Step 6).
89
+
90
+ **Caps.** Each CI run of the PR (the first one, every run after a fix push and every re-run) counts as one CI attempt. A round with no confirmed findings and CI green ends the step. Otherwise start the next round only while rounds remain under `review_rounds`; the next round reviews the new head. After the last round, keep driving CI alone (triage, fix agent with the CI failure only, re-runs) until it is green or `ci_attempts` attempts are used. If CI is still red after attempt `ci_attempts`, the change failed (Step 6).
91
+
92
+ ### Step 6: Gate
93
+
94
+ **Change succeeded** (every confirmed finding resolved by the fix check, and CI green):
95
+ - Single change: stop and report the PR ready for validation.
96
+ - Series: squash-merge the PR, sync main, then continue with the next change ID.
97
+
98
+ **Change blocked** (the implementer returned a blocker): never merge; stop the run, and bring the blocker to the user with its options. In series mode, do not start later changes.
99
+
100
+ **Change failed** (a confirmed finding the fix check marks not resolved, or CI still red after `ci_attempts` attempts):
101
+ - Never merge. Stop the run — in series mode, do not start later changes on top of a failed one.
102
+ - Report what failed: each unresolved finding with the fix check's reason, or the quoted CI error.
103
+
104
+ ## Exit
105
+
106
+ Report per change: branch, PR URL, review outcome (review rounds used, the findings not fixed with their verdicts, and the fix-check result per confirmed finding), CI status (CI attempts used), whether it was merged or awaits validation, and any blocker waiting on the user. In series mode, also state where the series stopped and why if it did not complete.
@@ -0,0 +1,38 @@
1
+ ---
2
+ description: Implement a change's tasks in the current session and tick them off
3
+ author: Amine
4
+ allowed-tools: Bash(theway:*)
5
+ ---
6
+
7
+ # TheWay: Develop
8
+
9
+ Implement a change as its spec describes it, inline in this session, and show that it meets its Success Criteria.
10
+
11
+ ## Locate the home
12
+
13
+ Run `theway path` and use the folder it prints as `<home>`: TheWay files are stored in `<home>/<project>/`, where `<project>` is your project directory name. Take `<home>` only from `theway path`, never from a path written in `config.yaml` or elsewhere.
14
+ - If `theway` is not found, tell the user to add the folder theway is installed in (`~/.local/bin` by default) to their `PATH`, or to run `/theway:setup`, and stop.
15
+ - If it fails with `error: unknown command 'path'`, the installed `theway` is older than these commands: tell the user to run `/theway:setup` and stop.
16
+ - Do not check for files under `<home>` before reading them. If reading `<home>/config.yaml` or a file under `<home>/data/` or `<home>/templates/` fails because it does not exist, theway is not set up: tell the user to run `/theway:setup` and stop.
17
+
18
+ ## Workflow Steps
19
+
20
+ > Follow the conventions in `<home>/data/standards/interaction.md` (exploration and reporting).
21
+
22
+ ### Step 1: Load Context
23
+
24
+ Take the change ID from the user's request (e.g. "develop the add-redis-cache change" → `add-redis-cache`); only ask if none is given. Run `theway path <project> <change-id>` and use the folder it prints as `<change-dir>`. Then read these exact paths directly — do not search the filesystem to locate them:
25
+ - `<home>/config.yaml` - Global config and conventions
26
+ - `<home>/data/standards/develop.md` - How a change is implemented and verified
27
+ - `<change-dir>/spec.md` - Why, what, risks and Success Criteria
28
+ - `<change-dir>/tasks.md` - The work, as numbered tasks
29
+ - `<change-dir>/design.md` - Technical specs (if present)
30
+ - `docs/architecture/coding-standards.md` - Project coding standards (if exists)
31
+
32
+ ### Step 2: Implement and Verify
33
+
34
+ Follow `<home>/data/standards/develop.md`: implement the tasks, stop and ask when the spec does not fit, then verify against the spec's Success Criteria. The change files you tick and update are the ones in `<change-dir>`.
35
+
36
+ ## Exit
37
+
38
+ Report the tasks done, each Success Criterion with how it was verified, any deviation from the spec and what was decided about it, and anything still open.
@@ -0,0 +1,58 @@
1
+ ---
2
+ description: Write architecture docs for the project in docs/architecture/
3
+ author: Amine
4
+ allowed-tools: Bash(theway:*)
5
+ ---
6
+
7
+ # TheWay: Document Mode
8
+
9
+ You are now in **Document Mode** - creating architecture documentation using templates.
10
+
11
+ **IMPORTANT:** Keep documentation practical and actionable, not verbose. Use code examples over explanations.
12
+
13
+ ## Locate the home
14
+
15
+ Run `theway path` and use the folder it prints as `<home>`: TheWay files are stored in `<home>/<project>/`, where `<project>` is your project directory name. Take `<home>` only from `theway path`, never from a path written in `config.yaml` or elsewhere.
16
+ - If `theway` is not found, tell the user to add the folder theway is installed in (`~/.local/bin` by default) to their `PATH`, or to run `/theway:setup`, and stop.
17
+ - If it fails with `error: unknown command 'path'`, the installed `theway` is older than these commands: tell the user to run `/theway:setup` and stop.
18
+ - Do not check for files under `<home>` before reading them. If reading `<home>/config.yaml` or a file under `<home>/data/` or `<home>/templates/` fails because it does not exist, theway is not set up: tell the user to run `/theway:setup` and stop.
19
+
20
+ ## Expected Output
21
+
22
+ Create project-specific architecture docs in `docs/architecture/`:
23
+
24
+ ```
25
+ docs/architecture/
26
+ ├── coding-standards.md # Project coding conventions
27
+ ├── source-tree.md # Repository structure
28
+ └── tech-stack.md # Technology choices
29
+ ```
30
+
31
+ ## Workflow
32
+
33
+ > Follow the conventions in `<home>/data/standards/interaction.md` (exploration and reporting).
34
+
35
+ ### Step 1: Generate Documents from Templates
36
+
37
+ First read `<home>/config.yaml` (and `<home>/data/standards/architecture-principles.md` if enabled in config).
38
+
39
+ Then, for each template below, read the template file, follow its frontmatter instructions (required_context, agent_role, workflow_steps, quality_standards, best_practices), and create/update the output file in `docs/architecture/` (overwrite if it already exists). Keep outputs concise — code examples, not verbose explanations.
40
+
41
+ | Template | Output |
42
+ |----------|--------|
43
+ | `<home>/templates/coding-standards-template.md` | `coding-standards.md` |
44
+ | `<home>/templates/source-tree-template.md` | `source-tree.md` |
45
+ | `<home>/templates/tech-stack-template.md` | `tech-stack.md` |
46
+
47
+ ### Step 2: Additional Documentation
48
+
49
+ Create other documentation as needed:
50
+ - System architecture overviews
51
+ - Backend design and API contracts
52
+ - Frontend architecture and patterns
53
+ - Infrastructure and deployment docs
54
+ - Technical decision records (ADRs)
55
+
56
+ ## Exit
57
+
58
+ When finished, summarize what was documented.
@@ -0,0 +1,84 @@
1
+ ---
2
+ description: Write the spec and numbered tasks for a change, without code
3
+ author: Amine
4
+ allowed-tools: Bash(theway:*)
5
+ ---
6
+
7
+ # TheWay: Engineering
8
+
9
+ You are now scaffolding a Spec analysis using templates.
10
+
11
+ > **What this command produces.** A spec someone else can implement without guessing: the problem, what you found out, the decisions and why, and the tasks. The code is written later, by `/theway:develop`, from that spec.
12
+ >
13
+ > Write only under `<change-dir>`, the change folder `theway path <project> <change-id>` prints (Step 2). Action words in the request ("rename X", "try the fix") describe what the spec should plan, not something to do now.
14
+ >
15
+ > Do **not** suggest entering plan mode — its approval step is a "start coding" trigger that collapses scaffolding into implementation.
16
+
17
+ ## Locate the home
18
+
19
+ Run `theway path` and use the folder it prints as `<home>`: TheWay files are stored in `<home>/<project>/`, where `<project>` is your project directory name. Take `<home>` only from `theway path`, never from a path written in `config.yaml` or elsewhere.
20
+ - If `theway` is not found, tell the user to add the folder theway is installed in (`~/.local/bin` by default) to their `PATH`, or to run `/theway:setup`, and stop.
21
+ - If it fails with `error: unknown command 'path'`, the installed `theway` is older than these commands: tell the user to run `/theway:setup` and stop.
22
+ - Do not check for files under `<home>` before reading them. If reading `<home>/config.yaml` or a file under `<home>/data/` or `<home>/templates/` fails because it does not exist, theway is not set up: tell the user to run `/theway:setup` and stop.
23
+
24
+ ## Workflow
25
+
26
+ > Follow the conventions in `<home>/data/standards/interaction.md` (exploration and reporting).
27
+
28
+ ### Step 1: Load Config and Standards
29
+
30
+ Read these files from `<home>`:
31
+ - `<home>/config.yaml` - Global config and conventions
32
+ - `<home>/data/standards/tamm-framework.md` - TAMM framework
33
+ - `<home>/data/standards/architecture-principles.md` - SRE-EE principles (if enabled in config)
34
+
35
+ ### Step 2: Create Change Folder
36
+
37
+ Use naming convention: `add-*`, `update-*`, `refactor-*`, `remove-*`
38
+
39
+ Example change IDs: `add-user-authentication`, `update-payment-api`
40
+
41
+ **Series naming**
42
+
43
+ - **Trigger:** the request is a series when the user asks for a series, for multiple sequential changes, or to "split into N changes", or when the argument passed already ends in `-NN`. In series mode the argument given to `/theway:engineering` is the `<series-id>`, not a change ID; if it already ends in `-NN`, strip that ordinal to get the `<series-id>` (never append a second one).
44
+ - **Pattern:** every member is `<series-id>-NN` — a shared verb-prefixed kebab-case `<series-id>` (same `add-`/`update-`/`refactor-`/`remove-` rule) plus a zero-padded two-digit ordinal starting at `01`, assigned in dependency order.
45
+ - **Continuation:** before assigning ordinals, run `theway path <project>` and use the folder it prints as `<project-dir>`, then `Glob` `<project-dir>/changes/<series-id>-[0-9][0-9]` and `<project-dir>/changes/archive/*-<series-id>-[0-9][0-9]` (archived folders are named `YYYY-MM-DD-<change-id>`; match only the exact `<series-id>`, not sibling series that merely end with it). Continue from the next free ordinal — never restart at `01`, never rename or renumber existing folders.
46
+ - **Forbidden:** topic-word suffixes (`add-user-auth-login`), letter suffixes in place of the ordinal (`-a`, `-b`; a standalone ID may still end in a one-letter word that is part of its name, e.g. `add-vitamin-c`, so a member of a series is always validated with `--series`), unpadded numbers (`-1`), mixing standalone IDs and series IDs within one series, and putting an ordinal on a single (non-series) change.
47
+ - **Example:** `add-user-auth-01`, `add-user-auth-02`, `add-user-auth-03`.
48
+
49
+ **Validate every ID before writing:** run exactly one form per ID — a standalone change: `theway validate-id <change-id>`; a series member: `theway validate-id <change-id> --series` only (never the form without `--series`, which rejects every `-NN` ID). It must exit 0 before any change folder is written. On exit 1 with an `invalid change id '<id>': <reason>` line on stderr, fix the ID from that reason and run it again. If it instead fails with `error: unknown command 'validate-id'`, the installed `theway` is stale: do not change the ID; stop and tell the user to run `/theway:setup`, then validate again. `validate-id` is the source of truth for the ID format.
50
+
51
+ **Locate the change folder:** once an ID is valid, run `theway path <project> <change-id>` and use the folder it prints as `<change-dir>` for that change (one per member in a series). Every file of the change is written there.
52
+
53
+ > The `Write` tool creates parent directories automatically — no need for explicit `mkdir`.
54
+
55
+ ### Step 3: Investigate
56
+
57
+ Before drafting, find out what the spec depends on: read the code involved, check how it behaves today, and settle the unknowns. You can clone repositories, run small throwaway scripts, call a service or measure something — whatever answers a specific question the spec has to settle.
58
+
59
+ Keep each investigation to its question. If you notice you are building the change itself to see whether it works, stop: a spec written after the code describes that code instead of the problem, and the blockers and alternatives it should have weighed are never examined. Turn what you were trying to learn into a question for the user, or record it in the spec as an open point.
60
+
61
+ What you learn goes into the spec as findings (question, method, result), not as code or diffs.
62
+
63
+ ### Step 4: Generate Documents from Templates
64
+
65
+ For each template below, read the template file, follow its frontmatter instructions (required_context, agent_role, workflow_steps, quality_standards, best_practices), and create the output file in `<change-dir>`:
66
+
67
+ | Template | Output |
68
+ |----------|--------|
69
+ | `<home>/templates/spec-template.md` | `spec.md` |
70
+ | `<home>/templates/tasks-template.md` | `tasks.md` |
71
+
72
+ For a series, each member's `spec.md` carries one line directly under its H1 title:
73
+ `**Series:** <series-id> — NN of TOTAL, depends on <series-id>-(NN-1)` — the `01` member states no dependency.
74
+
75
+ ### Step 5: Optional Technical Design
76
+
77
+ If needed, create `<change-dir>/design.md` for:
78
+ - API contracts and data models
79
+ - Architecture decisions
80
+ - Technical diagrams and specs
81
+
82
+ ## Exit
83
+
84
+ Report the change folder, the findings that shaped the spec, and any question still open. If a question is open, say so and stop; the spec is not ready until it is answered.
@@ -0,0 +1,24 @@
1
+ ---
2
+ description: List the active and archived changes of the current project
3
+ author: Amine
4
+ allowed-tools: Bash(theway:*)
5
+ ---
6
+
7
+ # TheWay: List Changes
8
+
9
+ ## Locate the home
10
+
11
+ Run `theway path` and use the folder it prints as `<home>`: TheWay files are stored in `<home>/<project>/`, where `<project>` is your project directory name. Take `<home>` only from `theway path`, never from a path written in `config.yaml` or elsewhere.
12
+ - If `theway` is not found, tell the user to add the folder theway is installed in (`~/.local/bin` by default) to their `PATH`, or to run `/theway:setup`, and stop.
13
+ - If it fails with `error: unknown command 'path'`, the installed `theway` is older than these commands: tell the user to run `/theway:setup` and stop.
14
+ - Do not check for files under `<home>` before reading them. If reading `<home>/config.yaml` or a file under `<home>/data/` or `<home>/templates/` fails because it does not exist, theway is not set up: tell the user to run `/theway:setup` and stop.
15
+
16
+ ## List
17
+
18
+ Use the current working directory name as `<project>` and run:
19
+
20
+ ```bash
21
+ theway list <project>
22
+ ```
23
+
24
+ Show the output to the user as-is.
@@ -0,0 +1,25 @@
1
+ ---
2
+ description: Install or update theway from a Claude Code session
3
+ author: Amine
4
+ allowed-tools: Bash(npx --yes github:pixelfactoryio/theway install)
5
+ ---
6
+
7
+ # TheWay: Setup
8
+
9
+ One-time setup: installs the `theway` CLI on your `PATH` and initializes the theway home with TheWay templates, standards, and configuration.
10
+
11
+ ## Steps
12
+
13
+ ### Step 1: Run the Installer
14
+
15
+ ```bash
16
+ npx --yes github:pixelfactoryio/theway install
17
+ ```
18
+
19
+ ### Step 2: Check the Result
20
+
21
+ If it exits non-zero, show its stderr to the user and stop.
22
+
23
+ ### Step 3: Report
24
+
25
+ Report its last line and tell the user to run `/reload-plugins`. If it printed an `Add <dir> to your PATH` line or a `theway: warning:` line, show those lines too: the commands find `theway` through `PATH`.
@@ -0,0 +1,170 @@
1
+ # TheWay Agent Instructions
2
+
3
+ > **Note:** TheWay files are stored in `<home>/<project>/`, where `<home>` is the folder `theway path` prints and `<project>` is your project directory name. `theway path <project> <change-id>` prints a change folder, `<change-dir>`.
4
+
5
+ ## TL;DR
6
+
7
+ **Two Main Workflows:**
8
+
9
+ 1. **Document Project** → Use `/theway:document`
10
+ 2. **Implement Changes** → Use `/theway:engineering` then `/theway:develop` then `/theway:archive`
11
+
12
+ ## Quick Reference
13
+
14
+ | Command | Purpose | Templates Used |
15
+ |---------|---------|----------------|
16
+ | `/theway:document` | Document architecture and technical decisions | `coding_standards`, `source_tree`, `tech_stack` |
17
+ | `/theway:engineering` | Scaffold spec analysis and implementation plan | `value_engineering`, `implementation_tasks` |
18
+ | `/theway:develop` | Implement tasks from change folder | Reads existing `spec.md`, `tasks.md` |
19
+ | `/theway:archive [id]` | Archive completed change to archive/ | N/A |
20
+
21
+ ## Template-Driven Workflow
22
+
23
+ ### How It Works
24
+
25
+ All TheWay workflows are **template-driven**:
26
+
27
+ 1. **Slash commands** load templates from `<home>/config.yaml`
28
+ 2. **Templates** contain complete instructions in YAML frontmatter:
29
+ - `usage` - When to use this template
30
+ - `agent_role` - Role/mindset to adopt
31
+ - `required_context` - Files to read first
32
+ - `quality_standards` - What makes a good instance
33
+ - `workflow_steps` - How to create the document
34
+ - `best_practices` - Tips and guidelines
35
+
36
+ 3. **Agents** follow template instructions to create documents
37
+
38
+ ### Template Registry
39
+
40
+ Templates are defined in the plugin's `config.yaml` (not in user's project directory).
41
+
42
+ ## Workflow 1: Document Project
43
+
44
+ **Command:** `/theway:document`
45
+
46
+ **Purpose:** Create/update architecture documentation
47
+
48
+ **Templates Used:**
49
+ - `coding_standards` - Project coding conventions
50
+ - `source_tree` - Repository structure
51
+ - `tech_stack` - Technology choices and rationale
52
+
53
+ **Expected Output:**
54
+ ```
55
+ docs/architecture/
56
+ ├── coding-standards.md # Project coding conventions
57
+ ├── source-tree.md # Repository structure
58
+ └── tech-stack.md # Technology choices
59
+ ```
60
+
61
+ **Process:**
62
+ 1. Create `docs/architecture/` directory
63
+ 2. Review existing `docs/` for gaps
64
+ 3. Load templates from plugin's config.yaml
65
+ 4. For each template: Read frontmatter → Follow instructions → Create document with correct filename
66
+ 5. Save to `docs/architecture/` directory (coding-standards.md, source-tree.md, tech-stack.md)
67
+ 6. Keep outputs concise, actionable, code-focused (not verbose)
68
+
69
+ **See:** `.claude/commands/theway/document.md` for complete workflow
70
+
71
+ ## Workflow 2: Implement Changes
72
+
73
+ ### Stage 1: Scaffold (Engineering)
74
+
75
+ **Command:** `/theway:engineering`
76
+
77
+ **Purpose:** Create spec analysis and implementation tasks
78
+
79
+ **Templates Used:**
80
+ - `value_engineering` - TAMM-based analysis
81
+ - `implementation_tasks` - Numbered task checklist
82
+
83
+ **Process:**
84
+ 1. Create change folder: `<change-dir>`, from `theway path <project> <change-id>`
85
+ 2. Load templates from plugin's config.yaml
86
+ 3. For each template: Read frontmatter → Follow instructions → Create document with correct filename
87
+ 4. Output: `spec.md` (from value_engineering template) and `tasks.md` (from implementation_tasks template) in change folder
88
+
89
+ **See:** `.claude/commands/theway/engineering.md` for complete workflow
90
+
91
+ ### Stage 2: Implement (Develop)
92
+
93
+ **Command:** `/theway:develop`
94
+
95
+ **Purpose:** Implement tasks from change folder
96
+
97
+ **Process:**
98
+ 1. Read `<change-dir>/spec.md` for context
99
+ 2. Read `<change-dir>/tasks.md` for checklist
100
+ 3. Implement tasks sequentially
101
+ 4. Check off tasks as completed: `- [x]`
102
+ 5. Update Notes section with discoveries
103
+
104
+ **See:** `.claude/commands/theway/develop.md` for complete workflow
105
+
106
+ ### Stage 3: Archive
107
+
108
+ **Command:** `/theway:archive [change-id]`
109
+
110
+ **Purpose:** Move completed change to archive with timestamp
111
+
112
+ **Process:**
113
+ 1. Verify all tasks checked off
114
+ 2. Move to archive: `<home>/<project>/changes/archive/YYYY-MM-DD-[change-id]/`
115
+ 3. Confirm completion
116
+
117
+ **See:** `.claude/commands/theway/archispec.md` for complete workflow
118
+
119
+ ## TAMM Framework Reference
120
+
121
+ **Quick Overview:**
122
+
123
+ - **Time (T):** Timeline constraints, dependencies, blocking risks
124
+ - **Autonomy (A):** Decision authority, organizational constraints, approval needs
125
+ - **Mastery (M):** Skill gaps, knowledge requirements, learning curves
126
+ - **Machine (M):** System limitations, performance constraints, infrastructure issues
127
+
128
+ **For complete TAMM reference:** See plugin's `data/standards/tamm-framework.md`
129
+
130
+ ## Change Folder Structure
131
+
132
+ ```
133
+ <home>/<project>/changes/[change-id]/
134
+ ├── spec.md # Spec analysis (required)
135
+ ├── tasks.md # Implementation checklist (required)
136
+ └── design.md # Technical design (optional)
137
+ ```
138
+
139
+ ## Naming Conventions
140
+
141
+ ### Change IDs
142
+ - Format: `[verb]-[description]` (kebab-case)
143
+ - Verbs: `add`, `update`, `refactor`, `remove`
144
+ - Examples: `add-user-auth`, `update-payment-api`, `refactor-error-handling`
145
+
146
+ ### Archive Format
147
+ - Format: `YYYY-MM-DD-[change-id]`
148
+ - Example: `2025-10-17-add-user-auth`
149
+
150
+ ## File Locations
151
+
152
+ **User's Project Files (created by commands):**
153
+ - `<home>/<project>/changes/` - Active change proposals
154
+ - `<home>/<project>/changes/archive/` - Completed changes with timestamps
155
+ - `<change-dir>/spec.md` - Spec analysis
156
+ - `<change-dir>/tasks.md` - Implementation checklist
157
+ - `<change-dir>/design.md` - Technical design (optional)
158
+ - `docs/architecture/` - Project architecture documentation
159
+
160
+ **Plugin Files (read-only reference):**
161
+ - Plugin's `config.yaml` - Template registry and configuration
162
+ - Plugin's `project.md` - TheWay methodology conventions
163
+ - Plugin's `data/standards/tamm-framework.md` - TAMM framework details
164
+ - Plugin's `data/standards/architecture-principles.md` - SRE-EE principles
165
+ - Plugin's `templates/*.md` - Template files with frontmatter instructions
166
+ - Plugin's `commands/*.md` - Slash command definitions
167
+
168
+ ---
169
+
170
+ **For detailed instructions on any template:** Read the template file's YAML frontmatter.