@tduyng/pi-devos 0.13.6 → 0.14.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.
Files changed (100) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/README.md +26 -33
  3. package/package.json +1 -2
  4. package/plugins/devos/agents/verifier.md +4 -30
  5. package/plugins/devos/pi/extension/devos.ts +16 -26
  6. package/plugins/devos/scripts/check-evidence-router.sh +7 -1
  7. package/plugins/devos/scripts/evidence-router.py +5 -3
  8. package/plugins/devos/scripts/gates/check-dod-core.sh +5 -3
  9. package/plugins/devos/scripts/gates/check-port-source.sh +1 -1
  10. package/plugins/devos/scripts/gates/check-scenario-coverage.sh +10 -8
  11. package/plugins/devos/scripts/gates/phase-gate.sh +6 -6
  12. package/plugins/devos/scripts/gates/plan-template-check.py +6 -12
  13. package/plugins/devos/scripts/gates/spec-contract.sh +19 -0
  14. package/plugins/devos/scripts/gates/spec-template-check.py +8 -21
  15. package/plugins/devos/scripts/gates/suite/01-dod.sh +485 -0
  16. package/plugins/devos/scripts/gates/suite/02-integrity.sh +310 -0
  17. package/plugins/devos/scripts/gates/suite/03-archetype.sh +255 -0
  18. package/plugins/devos/scripts/gates/suite/04-spec-validator.sh +183 -0
  19. package/plugins/devos/scripts/gates/suite/05-requires.sh +360 -0
  20. package/plugins/devos/scripts/gates/suite/06-clarify-adapters.sh +435 -0
  21. package/plugins/devos/scripts/gates/suite/07-lint-evals.sh +350 -0
  22. package/plugins/devos/scripts/gates/suite/08-converge.sh +591 -0
  23. package/plugins/devos/scripts/gates/suite/09-quality.sh +516 -0
  24. package/plugins/devos/scripts/gates/suite/10-eval-harness.sh +679 -0
  25. package/plugins/devos/scripts/gates/test-gates.sh +23 -4253
  26. package/plugins/devos/scripts/gates/test-integrity-rubric.sh +1 -1
  27. package/plugins/devos/scripts/gates/test-phase-gate.sh +5 -5
  28. package/plugins/devos/skills/build/SKILL.md +3 -3
  29. package/plugins/devos/skills/build/references/refactor.md +1 -1
  30. package/plugins/devos/skills/build/references/routes.md +4 -4
  31. package/plugins/devos/skills/frame/SKILL.md +22 -39
  32. package/plugins/devos/skills/frame/references/template.md +115 -0
  33. package/plugins/devos/skills/implement/SKILL.md +4 -4
  34. package/plugins/devos/skills/implement/references/dod.md +6 -1
  35. package/plugins/devos/skills/implement/references/implement.md +3 -1
  36. package/plugins/devos/skills/implement/references/plan.md +9 -27
  37. package/plugins/devos/skills/implement/references/resume.md +1 -1
  38. package/plugins/devos/skills/implement/references/verify-close.md +4 -3
  39. package/plugins/devos/skills/implement/scripts/ops-log.sh +2 -2
  40. package/plugins/devos/skills/implement/scripts/validate-spec.sh +17 -65
  41. package/plugins/devos/skills/init/references/context.md +1 -1
  42. package/plugins/devos/skills/review/SKILL.md +24 -47
  43. package/plugins/devos/skills/review/references/comments.md +13 -0
  44. package/plugins/devos/skills/review/references/reviewer.md +124 -0
  45. package/plugins/devos/skills/review/references/routing.md +35 -0
  46. package/plugins/devos/skills/review/scripts/__pycache__/prepare.cpython-313.pyc +0 -0
  47. package/plugins/devos/skills/review/scripts/prepare.py +763 -0
  48. package/plugins/devos/skills/spec/SKILL.md +5 -6
  49. package/plugins/devos/skills/spec/references/write-spec.md +36 -51
  50. package/plugins/devos/skills/spec/scripts/clarify.sh +4 -4
  51. package/plugins/devos/skills/status/SKILL.md +4 -4
  52. package/plugins/devos/skills/status/scripts/check-requires.py +4 -4
  53. package/plugins/devos/skills/status/scripts/convention-usage.sh +1 -1
  54. package/plugins/devos/skills/status/scripts/quality-correlation.sh +2 -25
  55. package/plugins/devos/scripts/gates/check-handoff.sh +0 -215
  56. package/plugins/devos/skills/design-taste/SKILL.md +0 -55
  57. package/plugins/devos/skills/design-taste/references/tells.md +0 -85
  58. package/plugins/devos/skills/design-taste/scripts/slop-scan.py +0 -305
  59. package/plugins/devos/skills/docs/SKILL.md +0 -22
  60. package/plugins/devos/skills/docs/references/backfill.md +0 -54
  61. package/plugins/devos/skills/docs/references/init.md +0 -43
  62. package/plugins/devos/skills/docs/references/status.md +0 -71
  63. package/plugins/devos/skills/docs/references/update.md +0 -80
  64. package/plugins/devos/skills/explain/SKILL.md +0 -45
  65. package/plugins/devos/skills/explain/references/quiz.md +0 -21
  66. package/plugins/devos/skills/frame/references/boundaries.md +0 -53
  67. package/plugins/devos/skills/frame/references/decompose.md +0 -96
  68. package/plugins/devos/skills/frame/references/impact.md +0 -43
  69. package/plugins/devos/skills/frame/references/interrogate.md +0 -68
  70. package/plugins/devos/skills/product/SKILL.md +0 -40
  71. package/plugins/devos/skills/product/references/planner.md +0 -54
  72. package/plugins/devos/skills/surgical-diff/SKILL.md +0 -23
  73. package/plugins/devos/skills/test-integrity/SKILL.md +0 -26
  74. package/plugins/devos/skills/verification-evidence/SKILL.md +0 -17
  75. package/plugins/devos/workflows/common/backlog-file-structure.md +0 -44
  76. package/plugins/devos/workflows/common/category-file-structure.md +0 -41
  77. package/plugins/devos/workflows/common/feature-line-format.md +0 -10
  78. package/plugins/devos/workflows/common/roadmap-file-structure.md +0 -51
  79. package/plugins/devos/workflows/common/suggest-categories.md +0 -76
  80. package/plugins/devos/workflows/common/suggest-milestones.md +0 -92
  81. package/plugins/devos/workflows/doc/doc-health.md +0 -137
  82. package/plugins/devos/workflows/doc/doc-writer.md +0 -44
  83. package/plugins/devos/workflows/doc/init-documentation.md +0 -196
  84. package/plugins/devos/workflows/doc/retro-documentation.md +0 -304
  85. package/plugins/devos/workflows/doc/templates/library.md +0 -58
  86. package/plugins/devos/workflows/doc/templates/service.md +0 -61
  87. package/plugins/devos/workflows/doc/update-documentation.md +0 -194
  88. package/plugins/devos/workflows/doc/write-documentation.md +0 -137
  89. package/plugins/devos/workflows/product/create-product-mission.md +0 -45
  90. package/plugins/devos/workflows/product/create-product-roadmap.md +0 -106
  91. package/plugins/devos/workflows/product/create-product-tech-stack.md +0 -19
  92. package/plugins/devos/workflows/product/gather-product-info.md +0 -25
  93. package/plugins/devos/workflows/product/resume-detection.md +0 -70
  94. package/plugins/devos/workflows/product/reverse-backlog.md +0 -118
  95. package/plugins/devos/workflows/product/reverse-domain-model.md +0 -86
  96. package/plugins/devos/workflows/product/reverse-product-plan.md +0 -81
  97. package/plugins/devos/workflows/product/reverse-tech-stack.md +0 -73
  98. package/plugins/devos/workflows/product/scan-deep.md +0 -113
  99. package/plugins/devos/workflows/product/scan-git.md +0 -122
  100. package/plugins/devos/workflows/product/scan-light.md +0 -154
@@ -1,45 +0,0 @@
1
- ---
2
- name: explain
3
- description: "DevOS: Walk a shipped change back to an engineer who did not watch it happen: what it does, why, and what to hold in mind."
4
- argument-hint: "[spec-name | git-range] [--quiz]"
5
- disable-model-invocation: true
6
- ---
7
-
8
- # /devos:explain
9
-
10
- DevOS spends its whole design keeping work out of your context: reads whose results are thrown away, groups you never watched, worktrees outside your checkout, a ten-line clean verdict. That is the token efficiency, and the bill for it is that the artifacts get smarter every spec while you do not. This is where you pay that bill back, on the specs where it is worth paying.
11
-
12
- **Nothing is written.** The output is this conversation. Understanding lives in you, not in another file DevOS has to keep true; `behaviors/`, `decisions.md` and `codebase-map.md` are already the durable layer.
13
-
14
- ## Step 1: Resolve the range
15
-
16
- `$ARGUMENTS`, first match wins:
17
-
18
- | Argument | Range |
19
- |---|---|
20
- | a spec name (active or archived) | that spec's branch commits: `git log --format=%H [spec-name]` if the branch exists, else the commits touching `devos/specs/**/[spec-name]/` and the files its `spec.md` Code Map names |
21
- | anything git resolves (`abc123..def456`, `HEAD~3..HEAD`, a branch) | verbatim |
22
- | empty | current branch against the repository's default branch; on the default branch, `HEAD~1..HEAD` and say so |
23
-
24
- Then read what exists, and only what exists: `spec.md` (Goal, Design Convergence, Boundaries), `decisions.md`, `verifications/verification.md`, `ops.jsonl` when present (the run's own timeline: cite it for when each phase happened and where a resume picked up, instead of inferring order from mtimes). A range with no spec folder is the normal case for S and B route work; explain it from the diff alone rather than declining.
25
-
26
- ## Step 2: Read the diff before writing a word about it
27
-
28
- `git diff --stat` for shape, then the actual hunks. Read the surrounding code too, and the tests: a diff shows what moved, not what it joined. You are explaining a system as it now stands, not narrating a patch.
29
-
30
- **Every claim carries its anchor**: `file:line`, a test name, a `D-n` from decisions.md, or a command's output. Same rule as a spike finding and a verifier verdict, and for the same reason. A walkthrough is the easiest thing in DevOS to fake, because a plausible summary of a diff reads exactly like an accurate one.
31
-
32
- Where you cannot ground something, say so in place: `unclear from the diff why the retry cap is 3, no decision recorded`. That line is worth more than a confident guess, and it is often the best question the engineer gets out of this.
33
-
34
- ## Step 3: Four sections, in this order
35
-
36
- 1. **Background.** What part of the system this touches and how it worked before. Assume the reader knows the language and this codebase's shape, not this corner of it. Two paragraphs at most, and skip it entirely when the change is self-contained.
37
- 2. **Intuition.** The idea, before any code. The smallest example that makes it obvious, a before/after in prose, an ASCII sketch where the change is structural (a call path, a state sequence, a data shape). Someone who stops reading here should still be able to say what the change does and why.
38
- 3. **The code.** Walk it in execution order, not file order and not diff order: entry point first, then what it calls, then where it lands. Group hunks that only make sense together. Skip mechanical churn (renames, import shuffles, formatting) after one sentence saying it is there.
39
- 4. **What was rejected.** From `spec.md`'s Rejected Additions and every `rejected:` entry in `decisions.md`, one line each. These are the highest-value lines in the spec folder and nothing else surfaces them. A reader who does not know which doors are already closed re-proposes them, which is the specific way understanding decays into rework.
40
-
41
- `--quiz` appends five questions. Read `references/quiz.md` when the flag is present, not before.
42
-
43
- ## Step 4: Record it
44
-
45
- If the range resolved to a spec with a `devos/specs/archive/[spec-name].quality.md`, set its 9th tab-separated field to `explained` (append the field where the row is shorter, leaving the earlier ones untouched). One `sed`, no model call. That column is what tells you in three months whether this command earned its place, or whether it is a thing that got built and never used.
@@ -1,21 +0,0 @@
1
- # The quiz (`--quiz`)
2
-
3
- Five multiple-choice questions, four options each, after the walkthrough. Answers and one-line explanations go in a collapsed block below all five, never inline.
4
-
5
- The quiz is a speed regulator, not an assessment. Reading a walkthrough produces a strong feeling of having understood it, and that feeling is uncalibrated. Five questions is the cheapest instrument that separates the two. Nothing in DevOS gates on the result and nothing should: a self-graded test the engineer can skip is theirs to use, and a hook that blocked on it would be theater.
6
-
7
- ## What a question must test
8
-
9
- **Answerable only by someone who read this diff.** The test: could a competent engineer who read the spec title and nothing else guess it? If yes, it is a general-knowledge question and it is measuring nothing. Anchor each question in something specific to this change: the order two calls happen in, what the code does with an empty input, which of two files owns a decision, what breaks if a constant moves.
10
-
11
- Aim at the parts with consequences: an invariant the code now depends on, an error path, a boundary the plan called out, a decision that could reasonably have gone the other way. Not trivia (a variable's name, a line count, a file's path).
12
-
13
- One of the five is a **why** question, not a what. Those are the ones that catch a reader who followed the mechanics and missed the point.
14
-
15
- ## Rules that keep it honest
16
-
17
- - **Place the correct answer deliberately.** Left alone, a model puts it in the same slot most of the time and the reader learns the tell instead of the code. Decide the five positions up front so each of A through D is used at least once, then write the options into those slots.
18
- - **Distractors are plausible and wrong.** Each should be something a reader who half-followed would actually pick: the behavior before this change, the thing the rejected approach would have done, an adjacent function's behavior. A joke option converts the question into a three-option question.
19
- - **Comparable length and specificity across options.** The longest, most qualified option being correct is the oldest tell there is.
20
- - **No "all of the above", no double negatives, no two options that are both defensible.** If two are defensible, the question is wrong, not the reader.
21
- - **The explanation cites the same anchor the walkthrough used**: `file:line`, a test name, a `D-n`. A question you cannot cite an anchor for is a question you invented.
@@ -1,53 +0,0 @@
1
- # Boundaries
2
-
3
- Read this in round 2, after the dimension rows. It covers the two facts that decide whether the ask is even buildable: the state we do not own, and the contract other people read.
4
-
5
- ## Who owns the fact the rule depends on
6
-
7
- Write the ask's rules as a list, and for each one name where the deciding state actually lives. A rule like "unavailable once X has happened downstream" is not ours to evaluate: another service owns X, and everything else in the frame follows from how we can ask it.
8
-
9
- ```
10
- | Rule | Deciding state | Owner | Call we need | Shape | Exists | Verdict |
11
- ```
12
-
13
- `Shape` is the part people skip and then discover late. Per item or in bulk, synchronous or derived from events, at read time or at write time: a dependency that exists per item and not in bulk makes the detail screen trivial and the list screen impossible. Those are the same feature to a PM and two different projects to us.
14
-
15
- Check `Exists` in their published surface, their client package, or their schema, and record the path. Never infer it from a service name.
16
-
17
- | Verdict | What it means | What round 4 does with it |
18
- |---|---|---|
19
- | fits | the call exists in the shape we need | a normal `build` row |
20
- | wrong shape | it exists, but not for this surface | one row for the surface it does fit, and either a fallback row or an `escalate` row for the rest |
21
- | absent | nothing exposes it | an `ask` row naming the call and payload we need, and every dependent row `Requires` it |
22
-
23
- ## The fallback, and what it costs
24
-
25
- When the shape is wrong, the standing alternative is a local projection: consume the owner's events, persist the flag on our side, and read it locally. Say the cost out loud in the same line, because it is a real one. A projection is a second copy of someone else's truth, so it can be stale, it is wrong for anything irreversible, and it has to be backfilled for rows written before we started listening.
26
-
27
- The split that follows holds in general: a projection is good enough to decide what a list offers, and never good enough to authorise the act. For an irreversible action, re-check with the owner at the moment of the write, even when a local flag already said yes.
28
-
29
- When the only honest verdict is "not feasible as asked", that is an `escalate` row with the alternative and its cost, not a quiet descope. The person who asked gets to choose between waiting for the dependency and paying for the projection.
30
-
31
- ## Who owns the rule, not just the data
32
-
33
- Before designing any of it, settle one question: is this rule our business or theirs? The answer decides the whole shape.
34
-
35
- When the rule is ours, we publish the decision as its own fact, and the others react to it. When the rule is theirs, they consume whatever we publish and apply their own judgement, and we stay out of it. The failure is encoding their rule in our code: it changes on their schedule, and we find out when a user complains.
36
-
37
- Write the verdict down, with who it was agreed with. An unagreed ownership question is a `decision` row, and it blocks the rows under it.
38
-
39
- ## What other people read from us
40
-
41
- Whatever this change publishes is a contract, and the frame's job is to name who reads it before it ships, not after. Find the consumers in the code first (`rg` the event name, the field, the route), then in the team map for the ones that live in another repository.
42
-
43
- - A consumer that must react to this change gets an `ask` row with its named owner. A consumer that merely keeps working gets a line of evidence saying you checked.
44
- - A payload carries what the consumer cannot derive on its own. The previous state is the usual example: a service that only sees the new value cannot tell what changed, so it either guesses or re-reads.
45
- - Prefer one event per fact that happened, with the identifiers and the type in the payload, over an event per variant. Decide it by asking the consumers what they will branch on, not by guessing on their behalf.
46
- - Change a contract by publishing the next version beside the current one. Renaming a field in place is a silent break when nothing enforces a consumer's schema, and the frame should note it as a finding when nothing does.
47
- - A compatibility window, old field and new field side by side, needs the row that deletes the old one, with an owner and a trigger. Without it the window never closes, and a year later nobody can say which name is current.
48
- - A single broad event that everything subscribes to has an unbounded contract: when you cannot list its consumers, you cannot change a field in it. Growing it by one more optional field is the cheap move each time and the reason it got that way. Note the cost when the ask does that, and prefer a narrow fact whose audience is known.
49
- - A deletion or a state change that other services have already copied needs its own published fact, or their copy keeps the row forever.
50
-
51
- ## Organisational blockers
52
-
53
- A missing permission, a repository you cannot read, an unowned package, a team that renamed something halfway: these stop the work as hard as a missing API, and they only move when a named person acts. Each becomes an `unblock` row with the person, what they must do, and the escalation path if they are away. Never leave it as "we need access".
@@ -1,96 +0,0 @@
1
- # Decompose
2
-
3
- Read this in round 4. The output is `tickets.md`: the story, the rows, the fog, the out of scope.
4
-
5
- ## The story is the demo, the ticket is the merge
6
-
7
- One ask is one story, and the story is what a user can finally do. A ticket is the smallest unit someone can be assigned and merge on its own without breaking `main`. Those are different sizes, and collapsing them is the classic frame failure in both directions: one giant vertical ticket nobody can split across two people, or six tickets whose only demo is the last one.
8
-
9
- So `tickets.md` states the story once, with the demo that proves it, then rows beneath it. The story carries the vertical slice. Each row carries one obligation in one deployable unit.
10
-
11
- ```markdown
12
- ## Story: <what the user can do when every row below has shipped>
13
- Demo: <the click-path or the call sequence that shows it>
14
- ```
15
-
16
- Each row answers "mergeable alone, reviewable by one person, deployable without the others". A row that only makes sense merged together with another row is one row.
17
-
18
- ## What multiplies rows
19
-
20
- Four multipliers, applied in this order. Each one is a question about the code, not a preference.
21
-
22
- | Multiplier | The question | What betrays it |
23
- |---|---|---|
24
- | Deployable unit | which services, repos or packages must each ship a change | the codebase map, the ownership column of round 2 |
25
- | Entity variant | how many code paths carry this rule | a parenthesised list in the ask, sibling entities in the domain model |
26
- | Obligation | which of enforce, afford, remediate this rule needs | a rule phrased as "not available when …" |
27
- | Consumer | who downstream must react to what we publish | the events row of round 2 |
28
-
29
- **The variant multiplier is the one that is always missed.** When the ask says "a document (type A or type B)", that is one sentence and often two endpoints, two permission checks and two screens, because the two types are separate aggregates in the code. Resolve the count against the domain model and the actual handlers before splitting, and say in the row which variant it covers. Two variants that genuinely share one handler are one row, and saying so explicitly is what stops the next session re-splitting it.
30
-
31
- ## One rule, three obligations
32
-
33
- A rule that forbids an action is never one ticket. It lands in three places, and whoever skips one ships a product where the button exists and then fails:
34
-
35
- - **enforce**: the writer refuses the action and says why, with the authoritative check at the moment of the write
36
- - **afford**: the client learns the action is unavailable before offering it, by reading a field we return rather than by re-deriving the rule
37
- - **remediate**: the user is told what makes it available again, or told plainly that nothing will
38
-
39
- Afford belongs to whoever owns the read model, enforce to whoever owns the write. One person often owns both. They are still two rows when a separate client ships against the field.
40
-
41
- ## Kinds
42
-
43
- | Kind | When | Route |
44
- |---|---|---|
45
- | decision | a fork is open and no code can be chosen until it closes | `R` |
46
- | spike | the answer is a fact nobody has, found by reading or measuring | `R` |
47
- | build | the behavior is known, the path is known | `S`, `M` or `L` |
48
- | wide refactor | one mechanical change whose blast radius crosses the tree | `C`, expand then migrate then contract |
49
- | fix | existing behavior is already wrong, found while framing | `B` |
50
- | ask | another team must build or publish something first | theirs, not ours |
51
- | escalate | the ask is not feasible as written and product must choose | nobody's until it is answered |
52
- | unblock | access, ownership or a permission is missing and a named person must act | nobody's, but it gates rows |
53
-
54
- A `decision` row states both reversal costs, not just the recommendation: what it costs to undo this choice later, and what it costs to undo the other one. Those two numbers are rarely symmetric, and the cheaper-to-reverse side usually wins over the one that looks tidier today. Modelling forks resolve this way more often than by argument: when two states are displayed in different places, filtered differently, and reached by different flows, they are two states, and merging them later is a migration rather than a redesign.
55
-
56
- `ask`, `escalate` and `unblock` rows are the ones a frame exists to produce. They are the difference between a split that can be worked on Monday and one that stalls on Wednesday. Each names a person or a team, never a role in the abstract. An `ask` row carries the payload or call shape we need, so the other team can size it without a meeting.
57
-
58
- A wide refactor never becomes a vertical slice. Sequence it as expand (add the new form beside the old, nothing breaks), migrate in batches sized by blast radius with each batch its own row, then contract (delete the old form once no caller remains, gated by every batch).
59
-
60
- ## The rows
61
-
62
- ```
63
- | # | Ticket | Kind | Unit | Variant | Route | Requires | Owner | Spec |
64
- ```
65
-
66
- `Unit` is the service, repo or package that ships it. `Variant` is which entity variant it covers, or `all`. `Requires` names the row numbers that gate this one, and once a spec exists for a row, its spec folder repeats the same edge as a `Requires:` line so `/devos:status` can see it. `Owner` is a person or a team for `ask`, `escalate` and `unblock` rows, and blank for ours. A row whose only reviewer is away is sequenced around that, not assigned and left to sit.
67
-
68
- Order so that everything with no `Requires` comes first. The first row is the smallest one that proves the shape end to end, which is usually the authoritative check rather than the screen.
69
-
70
- ### When a row has more than one shape
71
-
72
- A row whose subject can be built two ways gets one line per shape under `tickets.md`, with the one you would take and the reason in the same line: two routes per family or one route dispatched on origin, the check called live or the flag projected from events. Three at most, and never for a row that has one obvious shape, because a list of options on every row is how a frame turns into a menu nobody reads. The value is that the reviewer sees the shape you rejected and why, instead of rediscovering it in review.
73
-
74
- ## The tracker rows
75
-
76
- End `tickets.md` with `## For the tracker`, one block per row this session can file: a title that names the change and its subject in the project's tracker language, and one sentence saying what the row covers, ending where the row ends. Rewrite the title from the row, never copy the ticket table. A title that reads `Offer a void action on the payment detail page` is filable, and `Ticket 2` is not.
77
-
78
- The sentence carries what a reader of the board needs and nothing else: the surface, the rule, the failure it refuses. Leave the evidence trail, the row number and the route in the frame, they are not board material. Rows owned by another team get a title and a sentence too, because somebody still has to file them.
79
-
80
- ## The cap
81
-
82
- Six of our own `build` rows per story. Past six, say it is an epic, propose the first row to spec now, and mark the rest `not now`. `ask`, `escalate`, `unblock` and `not now` rows do not count against the cap: suppressing those is how a frame hides the work instead of sizing it.
83
-
84
- ## The fog
85
-
86
- Under `## Not yet specified`, everything you can tell is coming but cannot yet phrase sharply, one line each with the area to revisit. The test is whether you can state the question precisely now, not whether you can answer it. A sharp question that is merely blocked is a `decision` row. A blurry one is fog, and it graduates when the row in front of it closes.
87
-
88
- A known-bad experience with no design yet belongs here by name, not quietly dropped: a list where some items cannot be acted on, a failure path with no copy, a limit the current numbers already approach. Naming it is what lets the rest of the team think about it before it ships.
89
-
90
- ## A cut surface still owes the user something
91
-
92
- When a surface drops out of this round, say what the user sees there instead. A screen that silently offers nothing, or offers an action that then fails, is worse than the gap it was hiding. If the stopgap is awkward, and it usually is, that is exactly the line to put in the `escalate` row: the person who asked for the surface is the one who should weigh an awkward stopgap against waiting.
93
-
94
- ## The out of scope
95
-
96
- What this frame deliberately rules out, one line each with why, including an impact row you are choosing not to carry and a surface left for a later round. This is the section that stops the next session re-discovering the same ten ideas and treating them as new.
@@ -1,43 +0,0 @@
1
- # Impact
2
-
3
- Read this in round 2. Every dimension gets a row. A dimension you cannot judge is `not examined` with why, never a silent omission, because the omission is what the engineer would have to redo.
4
-
5
- | Dimension | What to look for | Where to look |
6
- |---|---|---|
7
- | Data | a column, a backfill, a nullable field that must stop being null, rows already written the old way | the schema, the migrations folder, row counts |
8
- | Clients | every client that consumes this capability, and which ones this round covers | the API consumers, the personas file |
9
- | Interface | a response field other code reads, a request shape, a breaking rename | the API surface, OpenAPI or schema files, callers |
10
- | Events | a published event's payload, a new consumer, replay and ordering | publishers, consumers, the event contracts |
11
- | Other services | a repository or package that reads this data or calls this path | the monorepo tree, the codebase map, `rg` on the entity name |
12
- | Ownership | the team that owns the code the change needs | CODEOWNERS, the capability index |
13
- | Authorization | who may do this, per role, tier and channel | the personas file, the guards or policies |
14
- | Money | amounts, tax, rounding, currency, anything invoiced or refunded | the domain model, the behavior ledgers |
15
- | Compliance | law, retention, numbering continuity, audit trail, an approved platform | `devos/product/constraints.md` |
16
- | Published docs | the help-centre article or in-app copy the change makes wrong | `devos/product/knowledge/`, the capability index |
17
- | CI and checks | a new check, a slower suite, a check nothing covers yet | the justfile or package scripts, the CI config |
18
- | Infrastructure | a queue, a job, a cron, a storage bucket, a cost that scales with rows | the deployment config, existing jobs |
19
- | Performance | an N+1, a full scan, a synchronous call on a hot path, a per-row rule on a list | the query the change adds, the current p95 if it is recorded |
20
- | Observability | how anyone would see this working or failing in production | existing logs, metrics, alerts |
21
- | Rollout | a flag, an order of deploys, a reversible first step | how comparable changes shipped, the git history |
22
- | Copy and i18n | user-visible strings, their language, their error cases | the translation files |
23
- | Security | who can reach the path, what input it trusts, whether it leaks another tenant's row | the guards and policies, the validation at the boundary |
24
- | Data lifecycle | what is created, erased or kept, for how long, who can ask for erasure, what the audit shows afterwards | the schema's delete behaviour, the retention rule, the activity log |
25
- | Support | what the helpdesk sees when this fails, and the sentence they will paste | the knowledge base, the error copy, the ticket history |
26
-
27
- Each row is one line: the dimension, the concrete impact, the evidence (`path` or article id), and `none found (looked at X)` or `not examined (why)` when there is no impact.
28
-
29
- ## Three rules that keep being learned late
30
-
31
- **A rule evaluated per row on a list must be answerable from state we hold.** A per-item call to someone else is fine behind one detail screen and ruinous behind a list that every user loads. The detail surface and the list surface are the same sentence in the ask and two different projects, so the impact row says which surface it priced.
32
-
33
- **A constraint that only holds because our own writer is narrow does not belong in the schema.** Once an external producer or a future feature can emit the wider shape, the column has to allow it, and the invariant lives in the code path that must keep it. Ask what shapes arrive from outside before tightening a column.
34
-
35
- **Price the rare branch before building for it.** When a rule's expensive branch looks rare, count it: a query against production data turns an argued case into a number, and a branch that has never occurred is a deferral with evidence instead of a guess. The count is a `spike` row when nobody can run it in the frame.
36
-
37
- ## The pre-mortem
38
-
39
- Then, in the same file: this ships, and a month later it is a production incident. Write the three most plausible stories, each with the detection that would have caught it and whether anything in the repository provides that detection today. A story that cannot be told concretely means a dimension above is still `not examined`.
40
-
41
- ## The rule
42
-
43
- An impact is not a ticket. Most rows end as a line in a spec's constraints or an acceptance criterion. Round 4 decides which rows earn their own ticket, and a row no ticket covers and no spec will carry is the one thing worth saying out loud in the hand-off.
@@ -1,68 +0,0 @@
1
- # Interrogate the ask
2
-
3
- Read this in round 3. The spec skill's `question-craft.md` holds the opposite discipline for the opposite case: a request that already says what to change, where zero questions is the normal outcome. Here the request does not say what to change, so questions are the work. Both rules agree on the part that matters: never ask what you could find out yourself, and never ask without proposing an answer.
4
-
5
- ## Audit the ask before you interrogate
6
-
7
- A thin ticket is thin somewhere specific. Name the defect, because a ticket that is wrong is not the same as a ticket that is short:
8
-
9
- 1. **It contradicts itself.** A rule that hides an action, then says the action returns once a state changes, silently promises a refresh. Two surfaces named for one exit path cannot both be true.
10
- 2. **It states the solution and not the problem.** "Delete from the preview" may be one answer to "undo a bad import". Say which sentence is the requirement and which is a proposal, and frame the requirement.
11
- 3. **It assumes a route, an endpoint or a field that does not exist.** Check the tree before it becomes a row.
12
- 4. **A criterion cannot be tested as written.** "The user will not notice" and "it is fast" have no observer. Name the observer and the number, or turn it into a question.
13
- 5. **It contradicts something already published.** A rule in the knowledge base, a decision row, a published contract. Quote it, then ask which one wins. The answer changes the rows, not the tone.
14
-
15
- Write each defect as a finding with its quote, and let the questions carry the choice. A defect nobody states becomes a row that ships it.
16
-
17
- ## Homework first
18
-
19
- Facts are your job. Decisions are the engineer's. Before a question is allowed into the round, it must survive this: the answer is not in the codebase, not in `devos/product/`, not in the help-centre knowledge, not in git history, and not in a closed spec. A question whose answer was on disk is a defect in the frame, not a thorough interview.
20
-
21
- Dispatch a subagent for a fact you need and keep working. Only the questions downstream of that fact wait.
22
-
23
- When `devos/product/knowledge/sources.tsv` exists, run its check before quoting a page: `python3 <plugin>/skills/absorb/scripts/knowledge.py --dir devos/product/knowledge check`. It costs no model tokens and names any in-scope source nobody has read yet. Pass `--lastmod` with a freshly fetched listing and it also names what changed since the last read, which makes a page stale for the part it carries.
24
-
25
- ## The frontier
26
-
27
- Map the ask as a decision tree: every decision branches into the ones that hang off it. The frontier is every decision whose prerequisites are already settled. Ask the whole frontier in one round, never a question whose answer depends on another question in the same round.
28
-
29
- Shape every question as finding, then proposal:
30
-
31
- ```
32
- **Q1. <the decision, as a question>**
33
-
34
- Found: <what the code, the artifacts or the sources say, with the path or article id>
35
- Unknown: <the fork this leaves open>
36
- Proposed: <the answer you would take, and why it is the smaller one>
37
- Owner: engineer | product | support | legal | <named person or team> | nobody
38
- Default if unanswered: <what work starts with>
39
- ```
40
-
41
- Use the harness's structured-question tool when the choices are enumerable, with your proposal as the recommended option.
42
-
43
- ## Owners
44
-
45
- Group the round by owner, because a question in front of the wrong person stalls for a day. Engineer: design, data, interfaces, sequencing. Product: actor, tier, price, copy, what the user sees when it fails. Support: what users ask for today and what the published docs promise. Legal or finance: retention, numbering, tax, compliance. Nobody: no one knows, so the default holds and `questions.md` records it as an assumption, not an answer.
46
-
47
- One owner is easy to forget and answers the most expensive questions: the team on the other side of a boundary. What a consumer needs in a payload, whether a rule is theirs or ours, whether a call exists in the shape we need. Guessing on their behalf is how a contract gets designed twice. Name the team, and the person on it if you know who, and say which rows wait on the answer.
48
-
49
- ## Four questions worth asking every time
50
-
51
- They keep producing findings, and none of them are answerable from our own code alone.
52
-
53
- - Which clients consume this capability, and which of them does this round cover? A capability shipped on one client and not another is a decision, so it should be a stated one.
54
- - Who owns the rule this feature depends on, us or the team whose state decides it?
55
- - How often does the expensive branch actually happen? Ask for the count, or propose the query.
56
- - What does the user see on the surface we are not building this round?
57
-
58
- ## The cap
59
-
60
- Three question rounds across the whole frame, counted over rounds 1, 2 and 4 together, each of which may ask at most one round. A frame that has spent three stops asking, records what is still open as owned assumptions with their defaults, and hands over what it has. An unanswered question never blocks the frame, it becomes a row in `questions.md` and a named assumption in whichever spec consumes it.
61
-
62
- When the engineer picks a heavier option than you proposed, re-challenge exactly once with the specific cost, then record `Engineer override: <choice>. Cost accepted: <cost>.` and move on.
63
-
64
- ## The gap pass
65
-
66
- Last, one pass for what nobody asked for and the evidence says is coming. Each item names its source: the status the ask leaves unreachable, the migration the data needs, the published article the change makes wrong, the permission no persona holds, the failure path with no copy, the limit the current numbers already approach. An item with no source is speculation and does not go in the file.
67
-
68
- Say which of these you are proposing as a ticket and which you are only recording. Finding ten more things to build is how a two-day ask becomes a quarter.
@@ -1,40 +0,0 @@
1
- ---
2
- name: product
3
- description: "DevOS: Plan the product mission, roadmap, and tech stack. Not for mapping an existing codebase."
4
- argument-hint: "[product description]"
5
- disable-model-invocation: true
6
- ---
7
-
8
- # [0] Product Planning Process
9
-
10
- You are helping to plan and document the mission, roadmap and tech stack for the current product. This will include:
11
-
12
- - **Gathering Information**: The user's product vision, user personas, problems and key features
13
- - **Mission Document**: Take what you've gathered and create a concise mission document
14
- - **Roadmap**: Create a phased development plan with prioritized features
15
- - **Tech stack**: Establish the technical stack used for all aspects of this product's codebase
16
-
17
- This process will create these files in `devos/product/` directory.
18
-
19
- ### PHASE 1: Gather Product Requirements
20
-
21
- Work through `${CLAUDE_SKILL_DIR}/references/planner.md` (if `${CLAUDE_SKILL_DIR}` was not expanded, it is this skill's own directory) to create comprehensive product documentation (mission.md, roadmap.md, backlog.md, backlog category files, tech-stack.md under `devos/product/`). Take everything the user gave about the product idea, purpose, features, target users, and any other details.
22
-
23
- ### PHASE 2: Inform the user
24
-
25
- After all steps are complete, output the following to inform the user:
26
-
27
- ```
28
- Your product planning is all set!
29
-
30
- ✅ Product mission: `devos/product/mission.md`
31
- ✅ Product roadmap: `devos/product/roadmap.md`
32
- ✅ Product backlog: `devos/product/backlog.md`
33
- ✅ Product categories: `devos/product/backlog/*.md`
34
- ✅ Product tech stack: `devos/product/tech-stack.md`
35
-
36
- 📋 **Roadmap** contains features planned in milestones.
37
- 📦 **Backlog** contains features not yet assigned to a milestone.
38
-
39
- NEXT STEP 👉 `/devos:init` to define the domain model (business vocabulary)
40
- ```
@@ -1,54 +0,0 @@
1
- You are a product planning specialist. Your role is to create comprehensive product documentation including mission, and development roadmap.
2
-
3
- # Product Planning
4
-
5
- ## Core Responsibilities
6
-
7
- 1. **Gather Requirements**: Collect from user their product idea, list of key features, target users and any other details they wish to provide
8
- 2. **Create Product Documentation**: Generate mission, and roadmap files
9
- 3. **Define Product Vision**: Establish clear product purpose and differentiators
10
- 4. **Plan Development Phases**: Create structured roadmap with prioritized features
11
- 5. **Document Product Tech Stack**: Document the tech stack used on all aspects of this product's codebase
12
-
13
- ## Workflow
14
-
15
- ### Step 1: Gather Product Requirements
16
-
17
- Read and follow `${CLAUDE_PLUGIN_ROOT}/workflows/product/gather-product-info.md`.
18
-
19
- ### Step 2: Create Mission Document
20
-
21
- Read and follow `${CLAUDE_PLUGIN_ROOT}/workflows/product/create-product-mission.md`.
22
-
23
- ### Step 3: Create Development Roadmap
24
-
25
- Read and follow `${CLAUDE_PLUGIN_ROOT}/workflows/product/create-product-roadmap.md`.
26
-
27
- ### Step 4: Document Tech Stack
28
-
29
- Read and follow `${CLAUDE_PLUGIN_ROOT}/workflows/product/create-product-tech-stack.md`.
30
-
31
- ### Step 5: Final Validation
32
-
33
- Verify all files created successfully:
34
-
35
- ```bash
36
- # Validate core product files
37
- for file in mission.md roadmap.md tech-stack.md backlog.md; do
38
- if [ ! -f "devos/product/$file" ]; then
39
- echo "Error: Missing $file"
40
- else
41
- echo "✓ Created devos/product/$file"
42
- fi
43
- done
44
-
45
- # Validate category files
46
- category_count=$(ls devos/product/backlog/*.md 2>/dev/null | wc -l)
47
- echo "✓ Created $category_count category files in devos/product/backlog/"
48
-
49
- echo "Product planning complete! Review your product documentation in devos/product/"
50
- ```
51
-
52
- ## User Standards & Preferences Compliance
53
-
54
- If `devos/standards/conventions.md` exists, make sure the product mission and roadmap don't conflict with the choices recorded there.
@@ -1,23 +0,0 @@
1
- ---
2
- name: surgical-diff
3
- description: "Implementing from an approved plan or spec, or scope drifts: keep edits scoped."
4
- user-invocable: false
5
- ---
6
-
7
- # Surgical diff
8
-
9
- Every changed line traces to a task group in the approved plan.
10
-
11
- - Before touching a file the plan doesn't list, name it and say why: one line is enough, silence is not.
12
- - Match the surrounding code's style, naming, and comment density, even where you'd choose differently. If `devos/standards/rules/` has a file scoped to what you're touching, its bullets are the convention, not a suggestion: read it before the edit, not after a violation is flagged.
13
- - Leave adjacent code as you found it: no drive-by refactors, comment rewrites, or reformatting. If you notice dead code or a latent bug outside scope, mention it in the report (or `decisions.md`): fixing it is a separate decision.
14
- - Clean up your own orphans: imports, variables, and functions that **your** change made unused go; pre-existing dead code stays.
15
- - When the codebase contradicts the plan, stop and say so (see the implement skill's HALT conditions): a surgical diff in the wrong place is a second bug, not a small fix.
16
-
17
- | Rationalization | Rebuttal |
18
- |---|---|
19
- | "While I'm here, I'll clean this up" | Cleanup without a plan sentence is a new, unapproved change. Mention it, don't make it. |
20
- | "This rename makes the code clearer" | It makes the diff bigger. The reviewer maps hunks to the plan, not to taste. |
21
- | "It's just formatting, no logic change" | Then it's a separate commit under its own decision, not smuggled into this one. |
22
-
23
- The test: could a reviewer map every hunk of the diff to a sentence in the plan? If a hunk has no sentence, either the plan grows (out loud) or the hunk goes.
@@ -1,26 +0,0 @@
1
- ---
2
- name: test-integrity
3
- description: "Editing or debugging tests: keep assertions independent and fix code before weakening tests."
4
- user-invocable: false
5
- ---
6
-
7
- # Test integrity
8
-
9
- Tests are the spec's teeth. Implementation bends to tests, never the reverse.
10
-
11
- - A failing test means the code is wrong until proven otherwise. Fix the code first.
12
- - Keep assertions at full strength: the passing version of a test checks everything the failing version checked.
13
- - A test that cannot disagree with the code is not a test. When the expected value is recomputed the way the implementation computes it (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), it passes by construction, and the assertion count is unchanged so no counting gate sees it. Expected values come from an independent source: a known-good literal, a worked example, the spec.
14
- - A test must fail when the code under test returns nothing. Stub it to return `undefined`, `[]`, `0`, or `""`. A test that still passes asserts nothing.
15
- - Keep tests running: no `.skip`, no commented-out cases, no deleted tests to get to green.
16
- - A test you believe is genuinely wrong gets said out loud: show why the asserted behavior contradicts the spec, and get agreement **before** changing it. Then the change is a spec correction, recorded in `decisions.md`, not a workaround.
17
- - Failures you didn't cause get proven, not waved off: show the same test failing on the base branch, or fix it.
18
-
19
- | Rationalization | Rebuttal |
20
- |---|---|
21
- | "The test was too strict" | The test is the spec's teeth: prove the spec disagrees, out loud, before touching it. |
22
- | "I'll skip it now, re-enable after the merge" | A skipped test is a deleted test with better manners. Fix the code now. |
23
- | "That failure is flaky / unrelated" | Show it failing on the base branch, or it's yours. |
24
- | "I asserted the value the code computes, the count is unchanged" | Then the test can never fail. Get the expected value from the spec or a worked example, not from re-running the code's own arithmetic. |
25
-
26
- The test: would the author of the failing test agree your change preserved its intent?
@@ -1,17 +0,0 @@
1
- ---
2
- name: verification-evidence
3
- description: "For completion reports or verification verdicts, state commands, findings, and build or test status."
4
- user-invocable: false
5
- ---
6
-
7
- # Verification evidence
8
-
9
- A verdict without evidence is an opinion.
10
-
11
- - Every PASS/CLEAN claim names the exact commands run and their exit status. "Tests pass" means you ran them **in this session**, never inferred from reading code.
12
- - A run that executed nothing is not evidence. Report the count beside the status (`npm test` → exit 0, 42 passed), and treat zero tests collected as UNVERIFIED, never PASS: `go test` with no test files, a filter matching no test, and `--passWithNoTests` all exit 0 having proved nothing.
13
- - Every finding carries `file:line`, the offending code, and why it's a gap. Every fix claim shows the check that now succeeds.
14
- - A check you couldn't run is reported as SKIPPED with the reason, never silently folded into a PASS. An honest UNVERIFIED beats a false PASS.
15
- - Partial coverage gets stated as partial: "checked these 6 files", not reported as full coverage.
16
- - Re-measure every number at report time, or label it unverified. In measured agent runs, confident numbers stated from memory were the only false claims in otherwise-correct reports.
17
- - Report failures faithfully: if 2 of 40 tests fail, the verdict is NOT DONE plus the failing output, not "mostly passing".
@@ -1,44 +0,0 @@
1
- ### Backlog File Structure
2
-
3
- ⚠️ **CRITICAL FORMAT RULES:**
4
- - File extension: **`.md`** (NOT `.yml` or `.yaml`)
5
- - Content: Pure Markdown (NO YAML frontmatter)
6
- - This is an index file linking to category files
7
-
8
- **Complete file example (`backlog.md`):**
9
-
10
- ```md
11
- # Product Backlog
12
-
13
- Index of features not yet planned in a milestone.
14
-
15
- ---
16
-
17
- ## Category: Product Planning
18
-
19
- [product-planning](backlog/product-planning.md)
20
-
21
- - [ ] Feature X [M] - [product-planning](backlog/product-planning.md) - No spec yet
22
- - [ ] Feature Y [L] - [product-planning](backlog/product-planning.md) - No spec yet
23
-
24
- ---
25
-
26
- ## Category: Verification System
27
-
28
- [verification-system](backlog/verification-system.md)
29
-
30
- (No features in this category)
31
-
32
- ---
33
-
34
- *Use `/devos:product` to plan these features into a milestone.*
35
- ```
36
-
37
- **Rules:**
38
- - NO YAML frontmatter (pure Markdown file)
39
- - One `## Category: [Name]` section per category
40
- - Link to category file right after the header
41
- - Features use universal format (see feature-line-format.md)
42
- - Empty category: `(No features in this category)`
43
- - `---` separator between each category section
44
- - Footer noting how to promote features to the roadmap
@@ -1,41 +0,0 @@
1
- ### Category File Structure
2
-
3
- ⚠️ **CRITICAL FORMAT RULES:**
4
- - File extension: **`.md`** (NOT `.yml` or `.yaml`)
5
- - Content: YAML frontmatter ONLY (between `---` delimiters)
6
- - NO markdown content after the closing `---`
7
- - File ends immediately after the closing `---`
8
-
9
- **Complete file example (`product-planning.md`):**
10
-
11
- ```md
12
- ---
13
- category_id: product-planning
14
- name: Product Planning
15
-
16
- features:
17
- - feature_id: backlog-grooming-cmd
18
- name: Backlog Grooming Command
19
- description: |
20
- Command to manage backlog features.
21
- size: L
22
- milestone: null
23
- spec: null
24
- finalized: false
25
- ---
26
- ```
27
-
28
- ↑ **File ends here. Nothing after the closing `---`.**
29
-
30
- **Rules:**
31
- - Empty array: `features: []`
32
- - IDs: kebab-case, must match `^[a-z0-9-]+$`
33
-
34
- **Feature fields:**
35
- - `feature_id` : Unique kebab-case identifier
36
- - `name` : Display name
37
- - `description` : Multi-line description (use `|` for block scalar)
38
- - `size` : XS, S, M, L, XL, XXL
39
- - `milestone` : null (backlog) or milestone ID (e.g., "M1-Mercury")
40
- - `spec` : null or path to spec folder
41
- - `finalized` : false (pending) or true (completed)
@@ -1,10 +0,0 @@
1
- ### Feature Line Format (Universal)
2
-
3
- This format is **identical** in roadmap.md and backlog.md.
4
-
5
- ```
6
- - [x] Feature Name [SIZE] - [category-id](backlog/category-id.md) - [Spec](path)
7
- - [ ] Feature Name [SIZE] - [category-id](backlog/category-id.md) - No spec yet
8
- ```
9
-
10
- **Rule:** `[x]` if `finalized: true`, `[ ]` otherwise.