@jwilger/pi-development-system 0.88.0 → 0.89.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Wilger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,9 +1,25 @@
 # pi-development-system
 
 A [pi](https://pi.dev) extension package representing my seasoned approach to
-software development using a full AI SDLC.
+software development using a full AI SDLC: work is sized, planned in proportion, built
+test-first in small slices, reviewed by fresh-context reviewers and delivered by trunk-based
+commits. Guards enforce what must hold; the rest is guidance with a recorded way out.
 
-> **Status:** under construction (see `docs/plan/development-system-plan.md`).
+## Install
+
+```sh
+pi install npm:@jwilger/pi-development-system
+```
+
+Then `/reload`. To move to a newer release use
+`pi install npm:@jwilger/pi-development-system@<version>`.
+
+Jev, the classifier behind the judgements, is optional. Without a credential configured, the checks
+that rest on a judgement do not run or fall back to a default: the motive behind a test change, whether a
+diff needs an ADR, the quality of a commit rationale and whether a commit mixes changes, the intent
+nudges, the verifier's check of the agent's own claims, and the lens and severity choices in review.
+The status line shows `jev offline` when that is so. Everything deterministic holds without Jev: the
+hard stops, the delivery mode, the review streak, red-first and the slice life cycle.
 
 ## Replaces pi-subagent-manager
 
@@ -22,6 +38,12 @@ what the current phase expects. When you say a slice is finished with no review
 it tells you to start one. The slash commands (`/devsys-start`, `/devsys-plan`, `/devsys-review`,
 `/devsys-lens-review`, `/devsys-adr`, `/devsys-event-model`) are shortcuts to the same tools.
 
+Skills cover the habits behind the gates: `tdd-canon`, `behaviour-tests`, `semantic-types`,
+`typed-errors`, `functional-core-imperative-shell`, `strict-lints`, `delivery-discipline`, `delegation`,
+`code-review`, the language profiles (`profile-rust`, `profile-typescript`), `profile-design-system` for UI
+work (tokens, then components; build from the design system's materials and log a snowflake),
+`threat-modelling` (proportional; a document only when the risk earns it) and the planning skills below.
+
 Product planning has a skill (`product-planning`: brief, decision register, follow-ups,
 terminology, journeys). `devsys_lens_review` plans a review of the brief by five product lenses and
 writes the packets to `docs/product/reviews/`; `devsys_adr_new` creates the next numbered ADR, and
@@ -35,7 +57,7 @@ Event modelling has a skill (`event-modelling`: three slice patterns, Given/When
 `devsys_event_model_check` validates a directory of slice files (schema v1) and renders the swimlane
 Markdown or a Mermaid diagram; each profile's `gwt-tests` reference turns scenarios into failing tests.
 A dedicated extension that offers `event_model_validate`, or `event_model.provider` in
-`.development-system.toml`, replaces the builtin tool (`docs/event-model-extension-contract.md`).
+`.development-system.toml`, replaces the builtin tool ([contract](https://github.com/jwilger/pi-development-system/blob/main/docs/event-model-extension-contract.md)).
 
 A slice has a life cycle: `implementing` → `reviewing` (when a review round starts) → `delivering`
 (review satisfied) → `idle`. Editing production source while delivering reopens `implementing`,
@@ -52,6 +74,95 @@ With `codemode` enabled (`"defaultTools": ["+codemode"]` in pi settings), rarely
 reached through scripts and the `judge_*` Jev wrappers exist for scripts only; without codemode
 the rarely used tools are declared directly and the wrappers are absent.
 
+## Configuration
+
+`.development-system.toml` at the repository root (version 1). Every key is optional; an unknown
+key is an error that names it. `/devsys-models` writes the `[models]` table for the models this
+machine can use.
+
+| Table | Keys | Meaning |
+| --- | --- | --- |
+| `[delivery]` | `mode` (`trunk`, `pull-request`, `local-only`), `trunk`, `remote` | Where work lands; the push guard follows it. `local-only` blocks every push. |
+| `[review]` | `required_clean_rounds` (3), `min_rounds` (1) | The clean streak a slice needs before commit. |
+| `[tracker]` | `kind` (`repo-files`, `github`; `jira` and `linear` are not implemented), `repo` | Backlog for `devsys_work_item`. |
+| `[profiles]` | `override` | Languages to apply (`rust`, `typescript`); empty means detect. |
+| `[models]` | one ordered candidate list per slot | See Model tiers below. |
+| `[routing]` | `"<difficulty>/<risk>" = ["<slot>", "<thinking level>"]` | What `devsys_route_task` recommends for a subagent. |
+| `[verifier]` | `max_per_session` (6) | Cap on Jev checks of the agent's own claims. |
+| `[cadence]` | `push_minutes` (60) | Minutes without a push before the cadence nudge. |
+| `[event_model]` | `provider` (`builtin`) | Another provider replaces the builtin validator. |
+
+## Model tiers
+
+Models are asked for by slot, never by id. Three capability tiers (`frontier`, `strong`, `fast`)
+and role slots built on them (`planning`, `advisor`, `implementer`, `reviewer`, `lens`,
+`researcher`, `jev`). A slot is an ordered list of candidates: `provider/id`, a family pattern
+such as `provider/gpt-*-sol` (the newest available id wins) or a slot reference such as `@strong`.
+The first candidate this machine has credentials for is used, so one committed file works across
+accounts. Pin an exact id to stop it rolling forward. `devsys_models` shows what each slot
+resolves to, and the system recommends a model for a phase but never switches yours.
+
+## Enforcement tiers
+
+- **Hard stops** fire for the non-negotiables (`principles/NON-NEGOTIABLES.md`): rewriting
+  published history, force-pushing, deleting remote branches, discarding work with `reset --hard`,
+  `--no-verify`, forbidden commit trailers, pushing onto a red trunk, breaking the delivery mode.
+  Only the user can approve one, once, and only with a UI: a headless run refuses.
+- **Soft gates** guard the defaults (`principles/DEFAULTS.md`): weakening tests, commit rationale,
+  mixed commits, red-first, lint suppression, an unreviewed slice, scope, model for the phase, a
+  skipped planning artifact, a missing ADR. A soft gate is passed by recording a departure with
+  `devsys_record_departure` (what, why, cost if wrong, how long it applies).
+- **Guidance** covers everything else: skills and the phase guide, never enforced.
+
+What the tiers do not cover, so you can decide what to trust:
+
+- **Subagents run unguarded.** A child session is started without extensions, so none of the guards
+  runs inside it. The coordinator commits, pushes and delivers; a subagent's prompt tells it not to,
+  and the coordinator reviews what it produced.
+- **The red-trunk stop needs `gh`.** It reads CI through an authenticated `gh`; where `gh` is missing
+  or offline the trunk reads as unknown and the push is not stopped on that ground.
+- **A departure is the agent's own call.** `devsys_record_departure` waives a soft gate (also with no
+  UI) and is written to the decision log; it is never available for a hard stop.
+- **Gating starts at `devsys_intake`.** With no slice open, the review and red-first gates are off.
+- **Editing gate configuration is not guarded** (`biome.json`, hooks, CI files); review catches it.
+
+## Decision log
+
+Every departure and approval is appended to `docs/decisions/YYYY-MM.md` in the repository, so the
+reasons survive compaction and are reviewable. Architecture-shaping decisions get an ADR in
+`docs/adr/` (`devsys_adr_new`); product decisions go in the decision register that the
+`product-planning` skill describes.
+
+## Commands
+
+All of them are shortcuts to tools; none is required.
+
+| Command | Does |
+| --- | --- |
+| `/devsys-start` | Size the work and propose the artifacts it needs. |
+| `/devsys-plan` | Plan a capability or product, then begin work once approved. |
+| `/devsys-review` | Run a fresh-context review round. |
+| `/devsys-lens-review` | Five product lenses review the brief. |
+| `/devsys-adr` | Create the next ADR. |
+| `/devsys-event-model` | Validate and render an event model. |
+| `/devsys-models` | Write the model matrix for this machine (`--check` to verify). |
+| `/devsys-ci` | Watch CI for the pushed commit. |
+| `/devsys-status` | Phase, slice, review streak, departures and Jev status. |
+| `/agents` | The vendored subagent manager. |
+
+## Agents
+
+Spawn with `agent_spawn`; `devsys_route_task` picks the model and thinking level. `advisor` gives
+read-only decision support, `implementer`, `coder` and `tasker` build (one task record each),
+`reviewer` reviews a diff in fresh context and submits through `devsys_submit_review`,
+`researcher` reads and cites, `architect` and `writer` design and draft, and the five `lens-*`
+agents (Cagan, Torres, Pichler, Perri, Rumelt) review a product brief.
+
+## Changelog
+
+`CHANGELOG.md` is generated from the commit history by `npm run changelog`. A release is the commit that
+changes the version, so run it after that commit exists; the file lists what has been committed so far.
+
 ## Development
 
 ```sh

package/agents/coder.md

@@ -46,7 +46,7 @@ You are a coder. You own a change, whether a feature, refactor, bug fix, or fron
 
 ## Boundaries
 
-- bash is not a sandbox. Use it to inspect, build, test, and run project tooling. Do not commit, push, install dependencies, or touch the network unless the task says to. Other agents may be editing this tree, so do not revert or restyle their changes.
+- bash is not a sandbox. Use it to inspect, build, test, and run project tooling. Do not commit, push, install dependencies, or touch the network unless the task says to. In this session no devsys guards run in your session, so the repository's rules are yours to keep: never weaken, skip or delete a test to get green, never add a lint suppression without a stated reason, never commit secrets, and leave commits, pushes and history to the coordinator. Other agents may be editing this tree, so do not revert or restyle their changes.
 - You cannot delegate. Send agent_update only when the plan changes or a failure is not obvious. If a missing decision, missing access, an exhausted budget, or a stalled investigation blocks you, call agent_pause with the evidence and stop.
 
 ## Handback

package/agents/tasker.md

@@ -56,3 +56,5 @@ Run a proportionate check: the one the task specifies, else a focused test, comm
 - **Gaps**: anything unverified or left for another role.
 
 Send agent_update only when criteria are met, a check fails, or scope is expanding. If blocked, call agent_pause with the blocker and stop.
+
+In this session no devsys guards run in your session, so the repository's rules are yours to keep: never weaken, skip or delete a test to get green, never add a lint suppression without a stated reason, never commit secrets, and leave commits, pushes and history to the coordinator.

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.88.0",
+  "version": "0.89.0",
   "description": "A pi extension package representing a seasoned approach to software development using a full AI SDLC.",
   "keywords": [
     "pi-package"
   ],
+  "license": "MIT",
   "author": "John Wilger",
   "repository": {
     "type": "git",
@@ -57,6 +58,7 @@
   "scripts": {
     "test": "node --experimental-transform-types --no-warnings --test \"test/**/*.test.ts\"",
     "test:jev": "node --experimental-transform-types --no-warnings --test \"test/live/*.live.ts\"",
+    "changelog": "node --experimental-transform-types --no-warnings scripts/changelog.ts",
     "check:jev": "node scripts/run-jev-fixtures.ts",
     "typecheck": "tsc --noEmit",
     "lint": "biome check --error-on-warnings .",

package/skills/profile-design-system/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: profile-design-system
+description: Design-system discipline for UI work - tokens before components, building only from existing design-system materials, and a logged decision when something does not fit. Use when a slice adds or changes user interface (components, styles, pages), when a repo has a design system or token files (*.tokens.json, .css, .scss, .tsx, .vue, .svelte), or when reviewing UI code for snowflakes and raw values.
+---
+
+# Design-system profile
+
+Brad Frost's stance, as this system applies it: the AI is deliberately constrained to the
+design system's materials. That constraint is what separates working inside a design
+system from vibe coding. Treat the agent as a smart but sometimes unsophisticated
+junior developer who has read the system's codebase and must follow its conventions.
+
+## Order of work: tokens, then components, then pages
+
+1. **Tokens.** Three tiers. Raw (`color-brand-green`) feeds semantic
+   (`theme-color-primary-background`), which feeds component (`button-primary-background`).
+   Components read the component tier; they never reach for a raw value.
+2. **Components.** Structure, behaviour and accessibility live in a structural component
+   library, kept apart from the aesthetic token layer. Do not fork a component to change
+   how it looks; change tokens.
+3. **Pages.** A page is the test of the system. Build it with real content in more than
+   one shape: a 40 and a 340 character headline, one and ten items, empty and error.
+   Anything that breaks goes back to the component, not into a page-level patch.
+
+## Defaults for a UI slice
+
+- **Use an existing component.** Search the design system first and name what you found
+  in the task record. The plan lists the states and variants the slice must show
+  (default, hover, focus, disabled, loading, empty, error, long content, narrow screen).
+- **No raw values in components.** No hex colours, pixel sizes, z-indexes or font
+  stacks inline. Make this a lint (stylelint, a biome or eslint rule, a grep in CI);
+  prose alone is a write-only channel and is not enforced.
+- **Build states outside the app first** when the repo has Storybook or a pattern lab:
+  write the story with real-content variants, then wire the component into the app.
+- **Accessibility is part of the component**, not a later pass: roles, labels, keyboard
+  path, focus order, contrast from the token pair, reduced motion.
+
+## When it does not fit: 90 percent and missing components
+
+Product pressure will find a way around the system. Decide, do not drift.
+
+| Situation | Decision | Record |
+| --- | --- | --- |
+| The component fits | Use it as is | nothing |
+| It fits about 90 percent | Extend through a documented variant or a token; ask the system owner when the variant is not yours to add | a line in the task record |
+| Nothing fits, and the need will recur | Propose a new component to the system, build it there first | an ADR if it changes the component API |
+| Nothing fits, and the need is one of a kind | A snowflake: allowed once, local, labelled | `devsys_record_departure` with gate `scope.expansion:snowflake`, naming the 90 percent reasoning and when to revisit |
+
+A snowflake written without that record is a defect to fix in review, not a style
+preference.
+
+## Checklist
+
+- [ ] The slice names the design-system components it uses, or why none fits.
+- [ ] No raw colour, size or font value in a component; the tier rule has a lint.
+- [ ] Every state and variant in the plan has a story or screenshot with real content.
+- [ ] Keyboard, focus, labels and contrast checked on the new or changed component.
+- [ ] Any snowflake or forked component has its recorded decision.
+
+## Do not
+
+- Do not invent a component, a token or a variant the system does not have without the
+  decision above.
+- Do not copy a component's markup into a page to restyle it.
+- Do not choose a different UI library for one slice.
+- Do not let a generated component through that only looks right in the happy case.

package/skills/threat-modelling/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: threat-modelling
+description: Proportional threat modelling for a change - decide whether it needs one, ask four questions, and record the result only when the risk earns it. Use before designing or reviewing anything that touches authentication, authorisation, secrets, user data, a network boundary, file or process execution, payments, or a new dependency, or when asked for a threat model or security review.
+---
+
+# Threat modelling
+
+Proportional on purpose. Most changes need thirty seconds of thought and no document.
+A few need a page. None need a framework exercise.
+
+## What this system trusts
+
+This system runs on the author's single-owner machine. Trusted: the author, their
+working tree, their credentials in pi, the local shell and git. Do not model an attacker
+who already has that. Untrusted: everything that arrives from outside it. That means
+network input, file contents from other people, dependency code, model output when it
+becomes a command or a path, and anything a deployed service receives.
+
+## Is a threat model needed?
+
+Ask all four and count the yes answers:
+
+1. Does the change add or move a **trust boundary** (a new input from outside, a new
+   network call, a new account or role)?
+2. Does it handle **secrets, personal data, money or authority** (login, permissions,
+   keys, tokens, payments)?
+3. Does it **execute or interpret** something it did not write (a shell command, a
+   file path, a template, deserialised data, a plugin)?
+4. Does it add a **dependency class** or change how packages are fetched or run?
+
+No yes: no document. Note "no new trust boundary" in the task record and move on. One or
+more yes: do the four questions below.
+
+## The four questions
+
+1. **What are we protecting?** Name the asset: the data, the authority, the money, the
+   machine. If you cannot name one, the change probably does not need this.
+2. **Who or what can reach it, and from where?** List the entry points and who controls
+   each: users, other services, files, the model, a dependency.
+3. **What could go wrong?** For each entry point, a line each for: pretending to be
+   someone else, changing what should not change, denying that it happened, reading what
+   should stay private, making it unavailable, gaining more authority than intended.
+   Skip the ones that do not apply and say so.
+4. **What stops it, and what is left?** Name the control that exists (a check, a limit,
+   a permission, a test). Where there is none, decide: build one, accept the risk, or
+   leave it to a named follow-up. An accepted risk is written down with its cost.
+
+## Checklist for the usual suspects
+
+- [ ] Input is parsed into a type at the boundary; length, size and shape limits exist.
+- [ ] Secrets never reach logs, commit messages, eval fixtures or subagent prompts
+      (non-negotiable 7); they are read from the environment or the credential store.
+- [ ] A path or a command built from input cannot leave its directory or add
+      arguments; use argument arrays, not string concatenation.
+- [ ] Authority is checked on the server side of every boundary, not inferred from the
+      client.
+- [ ] A failure refuses safely: with no user to ask, the answer is no.
+- [ ] Errors do not reveal more than the caller may know.
+- [ ] New dependencies are pinned, maintained and needed; the install does not run code
+      you did not intend.
+- [ ] Each control has a test that fails when the control is removed.
+
+## When to write `docs/security/threat-model.md`
+
+Write it, or extend it, when the change has at least two yes answers above, or any
+accepted risk you would want a reviewer to find later. Keep it to one page: assets,
+entry points, the table from question 3 for what applies, controls with their test
+names, accepted risks with who decided. Link it from the ADR when the decision shapes
+the architecture. Otherwise the task record line is enough.
+
+## Do not
+
+- Do not produce a threat model for a change with no trust boundary to satisfy a process.
+- Do not list generic threats that have no entry point in this system.
+- Do not accept a risk silently; an unrecorded acceptance is an unmanaged one.
+- Do not weaken a control to make a test or a gate pass (non-negotiable 2).