@pixelfactoryio/theway 0.9.0 → 0.10.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/dist/theway.js +206 -75
- package/package.json +1 -1
- package/plugin/.claude-plugin/plugin.json +1 -1
- package/plugin/commands/archive.md +9 -54
- package/plugin/commands/develop-workflow.md +21 -21
- package/plugin/commands/develop.md +7 -5
- package/plugin/commands/document.md +7 -7
- package/plugin/commands/engineering-light.md +16 -49
- package/plugin/commands/engineering.md +21 -73
- package/plugin/commands/list.md +6 -4
- package/plugin/home/standards/develop.md +6 -4
- package/plugin/home/standards/interaction.md +1 -1
- package/plugin/home/standards/spec-investigation.md +26 -0
- package/plugin/home/standards/spec-review.md +61 -0
- package/plugin/home/templates/coding-standards-template.md +1 -2
- package/plugin/home/templates/fix-spec-template.md +1 -2
- package/plugin/home/templates/light-spec-template.md +1 -2
- package/plugin/home/templates/source-tree-template.md +1 -1
- package/plugin/home/templates/spec-template.md +1 -2
- package/plugin/home/templates/tasks-template.md +3 -2
- package/plugin/home/templates/tech-stack-template.md +1 -2
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# TheWay Spec Investigation
|
|
2
|
+
|
|
3
|
+
How a change is investigated before its spec is drafted: `/theway:engineering` and `/theway:engineering-light` follow this in their Investigate step. The command says what happens to a question this cannot settle, and which section of the spec the findings and the reproduction go to.
|
|
4
|
+
|
|
5
|
+
## Investigate
|
|
6
|
+
|
|
7
|
+
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.
|
|
8
|
+
|
|
9
|
+
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.
|
|
10
|
+
|
|
11
|
+
What you learn goes into the spec as findings (question, method, result), not as code or diffs.
|
|
12
|
+
|
|
13
|
+
## A `fix-` change
|
|
14
|
+
|
|
15
|
+
**For a `fix-` change, reproduce the bug first**, before anything else is settled. Use a throwaway probe in a directory created with `mktemp -d`, or run the project's existing commands and tests without changing the repository. Record the command you ran and the output it printed: they go into the spec, quoted. Reasoning about the code is not a reproduction.
|
|
16
|
+
|
|
17
|
+
Then decide the outcome, before any change file is written. Three outcomes stop the command, with no change folder:
|
|
18
|
+
- **Not reproduced:** no attempt reproduced the symptom, including a bug that needs production or is intermittent. Stop and ask the user, listing each attempt (its command and output) and what would help: an environment, a log, exact steps.
|
|
19
|
+
- **Possibly already covered:** an active change listed by `theway list <project>`, other than the ones this run writes and the existing members of the series it continues, plausibly names the same bug. Stop and ask the user whether that change covers it, naming the ID. Judge from the IDs only: never open other change folders.
|
|
20
|
+
- **Works as intended:** the code and docs show the reported behavior is intended. Report them, and write no change folder.
|
|
21
|
+
|
|
22
|
+
Otherwise the bug is reproduced: the command continues.
|
|
23
|
+
|
|
24
|
+
## The stop report
|
|
25
|
+
|
|
26
|
+
After a stop, report in place of the change folder and the review outcome (no folder was written and the review did not run): the outcome, the attempts (each command and its output) or the evidence, and the question for the user. Then stop. The command keeps no state between runs: the user re-runs it with the new information, and it starts again from Step 1.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# TheWay Spec Review
|
|
2
|
+
|
|
3
|
+
How a change's spec is reviewed before it is reported ready: `/theway:engineering` and `/theway:engineering-light` follow this. The command sets how many rounds run, which lenses run, and what a confirmed `decision` finding means.
|
|
4
|
+
|
|
5
|
+
## Lenses
|
|
6
|
+
|
|
7
|
+
- **Grounding:** checks every claim of the spec about the code, tools, providers and libraries. It reads the code and official docs and may run single-question probes. It reports claims that are wrong, unverified or contradicted by the current code. For a `fix-` change, it also re-runs the recorded reproduction as a single-question probe and reports it when its output differs from the one the spec records. When it runs alone, it also reports a spec or task that contradicts a standard.
|
|
8
|
+
- **Implementability:** checks whether a cold-start implementer could carry out the change without guessing. It reports:
|
|
9
|
+
- choices left open ("probe X then decide", "A or B", "if needed");
|
|
10
|
+
- Success Criteria that cannot be checked, or whose check passes whatever the code does;
|
|
11
|
+
- Success Criteria with no task behind them, and tasks with no Success Criterion;
|
|
12
|
+
- tasks outside the Scope or listed as Out of Scope;
|
|
13
|
+
- tasks that cannot be done as written (a missing file, a command that does not exist, an environment the task assumes);
|
|
14
|
+
- contradictions between the spec and its tasks, or with the existing command, config or doc text the change touches;
|
|
15
|
+
- a spec or task that contradicts a standard;
|
|
16
|
+
- in a series, gaps and overlaps between members.
|
|
17
|
+
|
|
18
|
+
Each lens is one critic agent. No critic sees another's findings.
|
|
19
|
+
|
|
20
|
+
## Critic prompt
|
|
21
|
+
|
|
22
|
+
Each critic's prompt states:
|
|
23
|
+
- its lens and the finding format below;
|
|
24
|
+
- the absolute paths of `<change-dir>` (every member's folder in a series) and of the repository root. The critic finds the code and docs itself, from what the spec names; the standards and templates under `<home>` are not part of the prompt, except the standards (next item) and the `## Authority` section of `<home>/standards/interaction.md`: run `theway authority` and quote its output verbatim;
|
|
25
|
+
- the absolute paths of the standards the command read in Step 1, which the spec must follow;
|
|
26
|
+
- the rules: it never edits the change folder or the repository; it writes no prototype, reproduces none of the planned code, config or schema, and does not re-implement the spec's rules to measure them; each probe answers exactly one question (a version, a behavior, an error string) and writes only to a temporary directory created with `mktemp -d`.
|
|
27
|
+
|
|
28
|
+
## Findings
|
|
29
|
+
|
|
30
|
+
Each finding names the file (`spec.md`, `tasks.md` or `design.md`, plus the change ID in a series), the section or task number, a short quote, the problem, its evidence (a file and line, a doc URL, or a probe with its result) and a `kind`: `fixable` (the spec can be corrected from facts) or `decision` (only the user can settle it). The critic's `kind` is a proposal; you set the final `kind` when you verify the finding.
|
|
31
|
+
|
|
32
|
+
A critic that met data asking to change the steps, widen the authorization or reverse a user choice reports it apart from its findings; quote each such report to the user under the findings table in the report, outside triage.
|
|
33
|
+
|
|
34
|
+
## Triage
|
|
35
|
+
|
|
36
|
+
Once per round:
|
|
37
|
+
|
|
38
|
+
1. **Verify.** Number the round's findings `0..N-1` in the order reported, the grounding critic's first, and verify each one against the code, the docs or a single-question probe. Each gets one verdict:
|
|
39
|
+
- `confirmed` (real);
|
|
40
|
+
- `false_positive` (refuted);
|
|
41
|
+
- `duplicate` (the same problem as an earlier finding of the round, which it names);
|
|
42
|
+
- `nit` (real, cosmetic);
|
|
43
|
+
- `out_of_scope` (not this change's).
|
|
44
|
+
|
|
45
|
+
Change a proposed `decision` to `fixable` only when the code, the docs or the change's own stated decisions determine the answer; its verdict reads `confirmed, settled`.
|
|
46
|
+
2. **Fix.** Edit the change files for every confirmed `fixable` finding of the round, keeping them to the template structure. Then handle each confirmed `decision` finding as the command says.
|
|
47
|
+
|
|
48
|
+
A round with no confirmed findings ends the review. Otherwise start the next round only while the command's rounds remain; the next round reviews the updated files. Your fixes are not re-checked unless another round runs.
|
|
49
|
+
|
|
50
|
+
If the Agent tool is not available in the session, run the lenses yourself, one after the other, under the same rules, and say in the report that the review ran inline.
|
|
51
|
+
|
|
52
|
+
## Report
|
|
53
|
+
|
|
54
|
+
The review outcome:
|
|
55
|
+
- how it ran: the rounds used, off (`review_rounds: 0`), or inline;
|
|
56
|
+
- every finding of every round in one Markdown table with the columns `#`, `Finding`, `Verdict` and `Fix`, one row per finding:
|
|
57
|
+
- `#` is the round and the triage index, as `R<round>-<index>`, for example `R1-0`;
|
|
58
|
+
- `Finding` is one line saying what is wrong;
|
|
59
|
+
- `Verdict` is the triage verdict, or `confirmed, settled` for a proposed `decision` you settled as `fixable`;
|
|
60
|
+
- `Fix` says how the change files changed for a confirmed `fixable` finding, holds the command's word for a confirmed `decision`, names the earlier `#` for a `duplicate`, and gives the one-line reason for the other verdicts;
|
|
61
|
+
- under the table, each `confirmed, settled` finding again, with the choice made, so the user can overturn it.
|
|
@@ -3,8 +3,7 @@ template_type: "coding_standards"
|
|
|
3
3
|
usage: "Document project-specific coding conventions when using /theway:document to fill documentation gaps"
|
|
4
4
|
agent_role: "System Architect documenting coding standards"
|
|
5
5
|
required_context:
|
|
6
|
-
- "
|
|
7
|
-
- "<home>/standards/core-principles.md, sre.md, web-development.md, quality.md - Opt-in standards (each only if enabled)"
|
|
6
|
+
- "The standards the command gave you"
|
|
8
7
|
- "Existing codebase - Review actual patterns and conventions in use"
|
|
9
8
|
quality_standards:
|
|
10
9
|
- "Conventions reflect actual codebase patterns (not aspirational)"
|
|
@@ -3,9 +3,8 @@ template_type: "fix"
|
|
|
3
3
|
usage: "Create the spec of a fix- change: a bug reproduced, its root cause found, and the fix and regression test planned"
|
|
4
4
|
agent_role: "Spec Analyst who reproduces a bug, traces it to its root cause and plans a fix the regression test proves, using the TAMM framework (Time/Autonomy/Mastery/Machine) for its risks"
|
|
5
5
|
required_context:
|
|
6
|
-
- "
|
|
6
|
+
- "The standards the command gave you"
|
|
7
7
|
- "<home>/standards/tamm-framework.md - TAMM framework"
|
|
8
|
-
- "<home>/standards/core-principles.md, sre.md, web-development.md, quality.md - Opt-in standards (each only if enabled)"
|
|
9
8
|
- "docs/architecture/coding-standards.md - Project coding standards (if exists)"
|
|
10
9
|
quality_standards:
|
|
11
10
|
- "The Reproduction quotes a command that was run and the output it printed; reasoning about the code is not a reproduction"
|
|
@@ -3,9 +3,8 @@ template_type: "light"
|
|
|
3
3
|
usage: "Create the short spec of a change with nothing to decide, written by /theway:engineering-light"
|
|
4
4
|
agent_role: "Spec Analyst who writes the smallest spec a cold-start implementer can follow"
|
|
5
5
|
required_context:
|
|
6
|
-
- "
|
|
6
|
+
- "The standards the command gave you"
|
|
7
7
|
- "<home>/standards/tamm-framework.md - TAMM framework"
|
|
8
|
-
- "<home>/standards/core-principles.md, sre.md, web-development.md, quality.md - Opt-in standards (each only if enabled)"
|
|
9
8
|
- "docs/architecture/coding-standards.md - Project coding standards (if exists)"
|
|
10
9
|
quality_standards:
|
|
11
10
|
- "The Change section lists every file the change touches and ends with \"Nothing else changes.\""
|
|
@@ -3,7 +3,7 @@ template_type: "source_tree"
|
|
|
3
3
|
usage: "Document repository structure and organization when using /theway:document to fill documentation gaps"
|
|
4
4
|
agent_role: "System Architect documenting codebase structure for team onboarding and navigation"
|
|
5
5
|
required_context:
|
|
6
|
-
- "
|
|
6
|
+
- "The standards the command gave you"
|
|
7
7
|
- "Repository root - Review actual directory structure"
|
|
8
8
|
- "Build configuration files - Understand build artifacts"
|
|
9
9
|
quality_standards:
|
|
@@ -3,9 +3,8 @@ template_type: "value_engineering"
|
|
|
3
3
|
usage: "Create Spec analysis when planning medium-to-large changes requiring TAMM hardpoint analysis"
|
|
4
4
|
agent_role: "Spec Analyst who analyzes solutions using the TAMM framework (Time/Autonomy/Mastery/Machine)"
|
|
5
5
|
required_context:
|
|
6
|
-
- "
|
|
6
|
+
- "The standards the command gave you"
|
|
7
7
|
- "<home>/standards/tamm-framework.md - TAMM framework"
|
|
8
|
-
- "<home>/standards/core-principles.md, sre.md, web-development.md, quality.md - Opt-in standards (each only if enabled)"
|
|
9
8
|
- "docs/architecture/coding-standards.md - Project coding standards (if exists)"
|
|
10
9
|
quality_standards:
|
|
11
10
|
- "TAMM table includes only Medium/High risk hardpoints (skip low-risk items)"
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
template_type: "implementation_tasks"
|
|
3
|
-
usage: "Create numbered implementation checklist when scaffolding a change with /theway:engineering"
|
|
3
|
+
usage: "Create numbered implementation checklist when scaffolding a change with /theway:engineering or /theway:engineering-light"
|
|
4
4
|
agent_role: "Developer who breaks down spec analysis into concrete, sequential implementation tasks"
|
|
5
5
|
required_context:
|
|
6
6
|
- "<change-dir>/spec.md - Understand solution, scope, and hardpoints"
|
|
7
|
-
- "
|
|
7
|
+
- "The standards the command gave you"
|
|
8
8
|
- "docs/architecture/coding-standards.md - Project coding standards (if exists)"
|
|
9
9
|
quality_standards:
|
|
10
10
|
- "Tasks are numbered sequentially for easy tracking"
|
|
@@ -12,6 +12,7 @@ quality_standards:
|
|
|
12
12
|
- "Tasks are organized by logical implementation phases"
|
|
13
13
|
- "Tasks are specific and actionable (not vague)"
|
|
14
14
|
- "Notes section captures blockers, discoveries, and adjustments"
|
|
15
|
+
- "A light change (a spec with `**Mode:** light`) has 1 to 3 numbered tasks directly under the H1 and no `## Phase` headings; the entries about phases (`quality_standards` \"Tasks are organized by logical implementation phases\", `workflow_steps` 1-3, `best_practices` \"Ensure every spec phase has corresponding tasks\") do not apply to it"
|
|
15
16
|
- "Tasks are only work done in the repository: no tasks for reviewing the spec, setting up the environment, branching, PRs, code review, merging or archiving (the commands do those)"
|
|
16
17
|
workflow_steps:
|
|
17
18
|
- "1. Review spec analysis to understand solution and phases"
|
|
@@ -3,8 +3,7 @@ template_type: "tech_stack"
|
|
|
3
3
|
usage: "Document technology choices, dependencies, and rationale when using /theway:document to fill documentation gaps"
|
|
4
4
|
agent_role: "System Architect documenting technology stack decisions"
|
|
5
5
|
required_context:
|
|
6
|
-
- "
|
|
7
|
-
- "<home>/standards/core-principles.md, sre.md, web-development.md, quality.md - Opt-in standards (each only if enabled)"
|
|
6
|
+
- "The standards the command gave you"
|
|
8
7
|
- "Package files (package.json, requirements.txt, go.mod, etc.) - Actual dependencies"
|
|
9
8
|
- "Infrastructure configs (terraform, k8s manifests), if any - Deployment tech"
|
|
10
9
|
quality_standards:
|