pi-anchorloop 0.0.0-stage → 2.0.0

package/skills/anchorloop/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: anchorloop
+description: Use when a task runs while the user is away, is paused, or picks up a prior run's work (我要睡了, 跑到完成, 先暫停, 接手昨天的), and as the shared loop every entry skill runs.
+---
+
+# Anchor Loop
+
+Every entry skill (`answering`, `investigating`, `inspecting`, `coding`, `writing`, `solid-loop`) runs this loop and supplies the steps through one of its playbooks. The target project's instructions and an exact project skill govern where they speak.
+
+## Align
+
+Open with one working interpretation in your own words:
+
+    Alignment: <the requested task and intended outcome>
+
+Pick the entry's playbook from its index; with none fitting, run the loop bare. For work longer than one increment, copy the playbook's steps verbatim into `todo`, keeping each step you will not run as `skip: <reason>`, so the plan shows what was left out and why.
+
+## Anchor
+
+Before the first change, state:
+
+    Reality anchor: <the exact check that observes the result, and its checkpoint>
+
+The anchorloop extension holds `write` and `edit` outside `scratch/` and `docs/specs/` until this line appears after the user's latest message.
+
+Size the anchor to the change's actual reach and pick one method: an executable check, a user operation, human judgment, or a focused review. An anchor assigned by a coordinator governs. Pick a review anchor when the change touches a shared contract, authorization or permission data, a migration, or security, or when the Jev second thought rates its review `full`; other changes rest on their check and the author's own read of the diff. A review anchor names the realistic use it judges against and blocks on P0 and P1 findings only, recording lower ones as follow-ups; after fixes it re-checks only those findings and the lines the fixes changed, and when two consecutive rounds still raise new blocking findings the run stops and hands the trend to the user, because a fresh exploratory review each round finds new edge cases instead of converging. The checkpoint is normally once, after the last increment.
+
+## Act
+
+Work in the smallest useful increments through the project's native practices, deleting before adding (**Subtract before you add**).
+
+Give follow-up work (a fix round, a retry, the next item) to a fresh subagent carrying the original brief, every later directive, and the prior report and branch, because a resumed chain silently drops directives; resume an existing subagent only for state it alone holds, such as uncommitted changes or a running process. Write briefs, follow-ups, and messages to agents by [agent-terse](../agent-terse/SKILL.md); read each subagent's output and write its summary yourself.
+
+Report problems outside the contract as follow-ups rather than fixing them in this change, because each extra fix reopens review on code the round never meant to touch.
+
+[PRINCIPLES.md](PRINCIPLES.md) holds the named principles the playbooks cite. The reply names a principle only when it changed a decision, together with that decision.
+
+### Friction Notes
+
+Each time an attempt fails and a later attempt reveals why, append a note before continuing:
+
+    - Tried: <the attempt that failed>
+      Found: <what the failure revealed>
+      Led by: <the skill or instruction line that prompted the attempt, or `none`>
+
+Keep them in `scratch/friction.md` unless the entry names another home.
+
+### Decision Trail
+
+A run the user reviews after stepping away records one row per fork, completed unit, pivot, or blocker in `scratch/decisions-<task-slug>.tsv` with the `anchorloop_decision` tool. Evidence is a pointer (commit, `file:line`, artifact path), never prose, and a wrong call gets a superseding row instead of an edit. A run that picks up an existing trail reads its last rows, then records a `start` row with its run id. Before handing back, check every row against what the run actually did and build the report from the trail.
+
+## Verify
+
+Exercise the anchor and report what it observed. A requirement the anchor did not exercise is `unknown`; a green unrelated check is not evidence for it. Report local tests, builds, interactive runs, commit, push, CI, and deployment as separate claims; one never stands in for another. A criterion that needs human judgment is a human checkpoint: propose a `human-feedback` pass when it is still `unknown`, and record its verdict apart from executable or review evidence.
+
+A review anchor stays open until an independent reviewer returns its verdict. When none can run or its result is lost, report `blocked: independent review` and keep merge and release closed, because the author's own review, green tests, and CI each miss what an independent reader catches.
+
+Write the reply the playbook's `Reply:` line names, with the anchor's evidence. After a run that changed something, the extension may add a Jev second thought on that reply; it is advisory: recheck the evidence it questions, then finish or continue on your own judgment. When a calling workflow supplies an artifact, write the results into it instead of a separate report or plan.
+
+### Reflexive Pass
+
+Run only when friction notes exist, and say nothing about it otherwise. Classify each note: **misdirection** when the `Led by` line states or implies something `Found` contradicts; **gap** when no instruction in use states the `Found` fact. A gap the change itself resolved, or a tool slip no instruction owns, is recorded as resolved. Invoke `solid-loop` with the rest.
+
+**Complete when:** every requirement has evidence from its anchor or is reported `unknown`, and every friction note is applied through `solid-loop` or recorded as resolved.
+
+## Playbooks
+
+- [autonomous-run](playbooks/autonomous-run.md): the user steps away and the run drives to a predicate without them.
+- [pause](playbooks/pause.md): an explicit pause, going offline, a restart, or imminent compaction.
+- [pickup](playbooks/pickup.md): resuming or taking over a prior run's work.
+
+Lifecycle playbooks wrap the entry playbook that does the work.
+
+---
+
+Playbooks, principles, and the decision trail are adapted from [pstack](https://github.com/backnotprop/pstack) by Lauren Tan (MIT License), revision `e44668c`.

package/skills/anchorloop/playbooks/autonomous-run.md

@@ -0,0 +1,12 @@
+# Autonomous run
+
+**You own the exit condition.**
+
+1. Align: state the exit condition as a predicate a command or artifact can pass or fail; a duration is not one.
+2. Anchor: the predicate is the anchor. Set the wake mechanism: `MonitorCreate` with `onDone` or `onSignal` for an event (CI, a merge, a job), a `LoopCreate` heartbeat otherwise, plus one safety deadline.
+3. Act: each iteration makes the smallest change the evidence justifies, checks it against the predicate, commits when it advanced, and discards it when it did not.
+4. Act: record one decision-trail row per iteration.
+5. Act: fix reversible mid-run discoveries yourself in their own commits, then return to the predicate. Bring only irreversible actions, user-owned decisions, or a real dead end to the user, and leave them in the trail when the user is asleep.
+6. Verify: stop when the predicate holds. On a plateau, change approach; never relax the predicate to declare victory. A genuine dead end ends the run with a written reason.
+
+**Reply:** the exit condition, iterations run, what landed, what was discarded, and the final predicate state.

package/skills/anchorloop/playbooks/pause.md

@@ -0,0 +1,10 @@
+# Pause
+
+**You own a clean stop a cold-start agent can resume from.** Runs only on an explicit pause, going offline, a restart, or imminent compaction; "keep going" is not a pause.
+
+1. Stop at a safe boundary: finish or back out of the current step, start nothing new, and stop the subagents and monitors you started.
+2. Take no irreversible action to pause: no new push, PR, or deploy.
+3. Commit uncommitted work as one `wip:` commit on the current branch; when the tree is broken, say so in one line of the commit body.
+4. Write `scratch/resume-<task-slug>.md`: intent, what is done and verified, current state, the next action, key files, and gotchas. Point to the decision trail instead of copying it.
+
+**Reply:** where the run stopped, the `wip:` commit and whether the tree is clean, what lives only in the resume note, and the first action on resume.

package/skills/anchorloop/playbooks/pickup.md

@@ -0,0 +1,11 @@
+# Pickup
+
+**You own the resume point.**
+
+1. Locate the prior trail: the resume note, the decision trail, the branch, and this workspace's pi sessions only (the cwd's folder under the session directory: `~/.pi/agent/sessions/--Users-me-proj--/` for `/Users/me/proj` unless `--session-dir`, `PI_CODING_AGENT_SESSION_DIR`, or `sessionDir` moves it). Parse a long session in a subagent and keep the reduced timeline.
+2. Reconstruct state: branch and worktree, commits landed against the base, open todos, decisions made, and processes still running.
+3. Treat the trail as authoritative: name the resume point and redo nothing it shows finished.
+4. Route the remaining work to its entry playbook, which owns the rest of the run.
+5. Before reporting done, verify the inherited claims against the original goal on the real artifact; a prior self-report is not the proof.
+
+**Reply:** where the prior run stopped, what was inherited and what was redone, the resume point, and the outcome.

package/skills/answering/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: answering
+description: Use when explaining a concept or how something works, comparing technical alternatives, summarizing results or a change for the user, or when the user says they do not follow (看不懂, show me, 講清楚一點).
+---
+
+# Answering
+
+Run the loop in [../anchorloop/SKILL.md](../anchorloop/SKILL.md). The anchor is that every material claim carries its source and its evidence grade as `investigating` defines them; gather missing evidence through `investigating` first.
+
+Keep prose brief and state uncertainty where it lives. Show the shape beside the sentence it supports, with the smallest view that makes the point: a call tree or file tree for structure, pseudocode for logic, `A → B: message` lines for interaction, a table for options against criteria.
+
+## Playbooks
+
+- [explain](playbooks/explain.md): how something works, what changed, or what a result means.
+- [compare](playbooks/compare.md): choosing between alternatives.
+
+---
+
+The views are adapted from HumanLayer's [show-me](https://github.com/humanlayer/skills/tree/main/plugins/show-me) (MIT, © 2026 HumanLayer).

package/skills/answering/playbooks/compare.md

@@ -0,0 +1,9 @@
+# Compare
+
+**You own the recommendation.** A recommendation is a judgment, not an agreement.
+
+1. Fix the criteria that decide the choice before scoring any option.
+2. **Observe, don't ask** for any criterion a check can settle.
+3. Score each option against the criteria with evidence; say plainly when the premise or every option is wrong.
+
+**Reply:** the recommendation and its deciding reason, then the options-by-criteria table and what would change the pick.

package/skills/answering/playbooks/explain.md

@@ -0,0 +1,9 @@
+# Explain
+
+**You own the user's understanding.**
+
+1. Name the one mechanism or outcome the user needs and lead with it.
+2. For a change or result, start from what the user or the next maintainer will notice, then the cause; describe the change instead of showing a diff.
+3. Cut every section that does not move the user toward that point.
+
+**Reply:** the point in a line or two, then the supporting views with sources.

package/skills/coding/MINI-SDD.md

@@ -0,0 +1,61 @@
+# Durable phases and artifacts
+
+Read this when work is classified as durable. The threshold itself lives in [SKILL.md](SKILL.md); this file holds the Durable phases and what each artifact contains.
+
+Artifacts live in `docs/specs/YYYY-MM-DD-<slug>/`. Create each file when its phase is reached, not up front. Link to project instructions, ADRs, code, research, tickets, and visuals rather than copying them.
+
+## Decision → `decision.md`
+
+Resolve facts from their source; use `investigating` or `inspecting` when search is wide. Invoke `grilling` with `decision.md` only when it has an `open` row. Check that core rules are ready before implementation.
+
+The file holds outcome and actors; in and out of scope; concrete scenarios; confirmed decisions; open consequential decisions. Explore every consequential branch in:
+
+```markdown
+| Question | Answer | Basis | Status |
+|---|---|---|---|
+| ... | ... | request, evidence, or decision link | grounded, confirmed, or open |
+```
+
+Status is `grounded`, `confirmed`, or `open`. `grounded` comes from the request, source facts, or existing decisions; `confirmed` comes from the user; `open` is a consequential user-owned decision.
+
+**Complete when:** no open row blocks observable behavior.
+
+## Spec → `spec.md`
+
+State the observable contract, edge cases, compatibility constraints, non-goals, and the applied project standards. Persist it in `spec.md` under `Status: proposed` before presenting it, then await explicit user confirmation. `proposed` keeps production source untouched while artifacts and read-only work stay open. Only the user's approving reply sets `Status: approved`, `Approved at`, and `Approved from`.
+
+The file opens with the approval header, then observable behavior and edge cases; compatibility constraints and non-goals; applied standards with their impact; evidence and precedent links; the selected reality anchor and checkpoint.
+
+```markdown
+Status: proposed | approved
+Approved at: <date the user approved, empty while proposed>
+Approved from: <the user reply that approved it, empty while proposed>
+```
+
+## Design → `design.md`
+
+Choose the smallest approach that fits the approved spec and architecture. Follow the matching playbook's design steps ([feature](playbooks/feature.md) for interfaces and seams, [prototype](playbooks/prototype.md) when a named question is cheaper to settle by experiment) and the project's exact skill.
+
+The file holds the chosen approach; interfaces and data flow affected; existing precedent; decisions, trade-offs, and risks; the method selected inside the reality anchor. A straightforward design may be short, but it still names precedent and seam. Friction notes recorded during Act go under `## Friction Notes`.
+
+**Complete when:** implementation invents no product behavior or architecture.
+
+## Verify → `verification.md`
+
+Review the diff against project standards, the approved spec, and the confirmed domain model; dispatch a verification agent when the anchor needs an independent observer. Give every requirement in `spec.md` its own row:
+
+```markdown
+| Requirement | Evidence | Result |
+|---|---|---|
+| Observable behavior from spec | Real interface executed and the specific output observed | pass / fail / unknown |
+```
+
+- **pass**: The reality anchor ran against the actual implementation and directly observed the expected behavior.
+- **fail**: The anchor executed and observed a deviation from the spec or an error.
+- **unknown**: No anchor exercised the requirement in this run.
+
+Then human appropriateness verdicts; deviations from the approved spec or design; unresolved verification gaps and their impact. When friction notes exist, include a Reflexive section listing each with its classification (`misdirection` or `gap`) and its action.
+
+## Updates
+
+Update the owning phase file when new information changes it. A new consequential decision returns to `decision.md`; a change to user intent or observable behavior returns to Spec and user confirmation.

package/skills/coding/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: coding
+description: Use when changing source code or its tests, such as fixing a bug, adding or changing behavior, refactoring, improving performance, or prototyping a design question.
+---
+
+# Coding
+
+Run the loop in [../anchorloop/SKILL.md](../anchorloop/SKILL.md) with one of the playbooks below. Return to Align when user intent or observable behavior changes.
+
+## Classify
+
+Before the first production edit, declare the change **Inline** or **Durable**:
+
+- **Inline:** requirements and approach are clear, impact is bounded, and implementation and verification fit this run; a lasting behavior or public contract can still be Inline when the change is simple. Follow Alignment with `Inline — Contract: <one sentence of the observable behavior after the change>`; the user's source-change request approves it, and approval already given is not asked again.
+- **Durable:** the work needs a persistent design record because of material ambiguity, consequential trade-offs, cross-component coordination, migration risk, continuity across sessions, or a user-requested spec. Read [MINI-SDD.md](MINI-SDD.md) and create or resume its folder, which keeps no `tasks.md`; Spec waits for the user's approval before any production edit.
+
+## Anchor
+
+Point the anchor at what the change touches: a one-line edit anchors on the tests that assert that file; a shared code path anchors on its callers' tests. For Inline work, a green anchor plus a read of your own diff completes Verify; report the contract with its observed output in one line. Durable work verifies into `verification.md` as MINI-SDD describes.
+
+## Playbooks
+
+- [bug-fix](playbooks/bug-fix.md): broken, failing, slow-for-a-reason, or intermittent behavior.
+- [feature](playbooks/feature.md): new or changed behavior, or an interface that crosses a module.
+- [refactoring](playbooks/refactoring.md): structure changes, behavior does not.
+- [perf](playbooks/perf.md): a measured slowness to improve against a baseline.
+- [prototype](playbooks/prototype.md): disposable code that settles a design or behavior question.

package/skills/coding/playbooks/bug-fix.md

@@ -0,0 +1,11 @@
+# Bug fix
+
+**You own the root cause.** Every shipped line traces to runtime evidence.
+
+1. Anchor: build one tight, agent-runnable loop that asserts the user's exact symptom (failing test, request script, CLI fixture, browser check, replay, bisection, or differential comparison) and watch it go red. For flaky behavior, raise and measure the reproduction rate. Minimize it until every element is load-bearing. When no red-capable loop can be built, report what is missing and ask for that evidence instead of theorizing from code.
+2. Act: when the red loop does not already point at the cause, write three to five falsifiable hypotheses with predicted observations and test them one variable at a time, preferring a debugger, then logs tagged `[DEBUG-xxxx]`.
+3. Act: when two fixes resting on one premise fail the same loop, apply **Attack the premise** before a third: a contradicted premise sends you back to the hypotheses; a confirmed one means the fixes treated a consequence, so ask the next why.
+4. Act: an architectural cause returns to Classify as Durable. Otherwise turn the minimized repro into a regression test at the public seam, committed failing before the fix when that is cheap (**Sequence verifiable units**), and make the smallest change that turns it green. A change the evidence did not motivate is reverted.
+5. Verify: run the regression test and the affected suite on the surface the user saw, then remove every `[DEBUG-xxxx]` probe and throwaway artifact.
+
+**Reply:** what was broken, the root cause, the fix, and the failing-then-passing output.

package/skills/coding/playbooks/feature.md

@@ -0,0 +1,15 @@
+# Feature
+
+**You own the design.**
+
+1. Align: learn how the affected subsystem works now, and name the data shape and its organizing structure (**Model the domain**, **Foundational thinking**) before any logic.
+2. Act: when the change crosses a module, settle its interface first. Place the seam at an existing boundary; add one only for real variation, because one adapter is hypothetical and two demonstrate variation. Hide invariants and ordering behind the interface, and make it the test surface. A module whose removal makes complexity vanish rather than move to callers is a pass-through; delete it. With no precedent and a costly-to-reverse choice, compare two interface shapes on depth, locality, compatibility, and testability, or settle it with the `prototype` playbook; a user-owned trade-off goes to the user.
+3. Act: for more than one unit, write the throughput checkpoint as four `todo` items, each `n/a: <reason>` when it does not apply: blocking first steps; independent workstreams; shared mutable state, split before serializing; the smallest safe decomposition.
+4. Act: build in units that each end in a check (**Sequence verifiable units**).
+5. Verify: on the surface the user will use; an inconclusive or wrong-surface result is not a pass.
+
+**Reply:** what was built, the shape chosen and why, the checkpoint, and open decisions; a table when alternatives were compared.
+
+---
+
+Interface checks adapted from [mattpocock/skills](https://github.com/mattpocock/skills) `codebase-design` (MIT License, Copyright (c) 2026 Matt Pocock).

package/skills/coding/playbooks/perf.md

@@ -0,0 +1,10 @@
+# Perf
+
+**You own the number.**
+
+1. Anchor: measure a baseline on the real workload, repeated, with its range.
+2. Act: **Explain the number**: find what limits it and rule out a warm cache, a skipped path, or a debug build before trusting it. Profile before changing code.
+3. Act: one change at a time against the baseline; keep a change only when its gain sits outside the noise, and revert the rest.
+4. Verify: rerun the baseline workload under the same conditions.
+
+**Reply:** faster, slower, no measurable difference, or inconclusive, with run counts, ranges, what limits the number, and the profile that pointed at the change.

package/skills/coding/playbooks/prototype.md

@@ -0,0 +1,14 @@
+# Prototype
+
+**You own the decision, not the code.** The prototype is a throwaway instrument; the real build follows `feature`.
+
+1. Align: write the one question the prototype answers, the observation that settles it, and who owns the verdict. Choose a prototype only when running an experiment is cheaper or clearer than deciding from existing evidence.
+2. Act: build the smallest experiment in the project's native runtime, near its subject and visibly marked as a prototype, with ephemeral state unless persistence is the question. Implement only what observing the answer needs, and expose the state it depends on. Alternatives sit behind one switch, each labeled.
+3. Verify: observe the thing being decided (output, timing, a screenshot of each variant). When the remaining verdict is suitability, the human anchor's reviewer judges it.
+4. Record the question, environment, evidence, verdict, and decision in `design.md`, or in the reply when there is none. Delete the prototype afterward unless the user or project keeps it; it is committed only when the delivery workflow authorizes it.
+
+**Reply:** the variants, the evidence, the trade-offs, a recommendation, and the scratch path, stated as throwaway.
+
+---
+
+Adapted from [mattpocock/skills](https://github.com/mattpocock/skills) `prototype` (MIT License, Copyright (c) 2026 Matt Pocock).

package/skills/coding/playbooks/refactoring.md

@@ -0,0 +1,12 @@
+# Refactoring
+
+**You own the behavior contract. The structure changes; the behavior does not.**
+
+1. Anchor: pin current behavior with a characterization test, snapshot, or equivalence run before anything moves; a type check and lint are not a pin.
+2. Align: name the target shape as if built today, and the branches or invalid states it deletes. A reshape that only adds indirection is not one.
+3. Act: **Subtract before you add**.
+4. Act: move in small steps with the pin green. **Migrate callers, then delete**. Check each rename against strings, prose, and back-references.
+5. Act: a bug or missing feature found on the way becomes a follow-up; the structural change ships against the pinned contract first.
+6. Verify: prove equivalence on the real artifact, then confirm reader load dropped (**Minimize reader load**); when it did not, revert.
+
+**Reply:** the structure that changed, the pin, the equivalence evidence, the reader-load change, and what was reverted.

package/skills/domain-modeling/ADR-FORMAT.md

@@ -0,0 +1,47 @@
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily — only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
+- **Considered Options** — only when the rejected alternatives are worth remembering
+- **Consequences** — only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.

package/skills/domain-modeling/CONTEXT-FORMAT.md

@@ -0,0 +1,60 @@
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `CONTEXT.md` exists, single context
+- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

package/skills/domain-modeling/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: domain-modeling
+description: Use when project terminology or domain boundaries need refinement.
+---
+
+# Domain Modeling
+
+Actively reconcile the user's language, the project's glossary, and code. Return
+confirmed terms and decisions to the caller's artifact, or in the reply when
+there is none.
+
+## Discipline
+
+1. Read the applicable `CONTEXT.md`; follow `CONTEXT-MAP.md` when the repository
+   has multiple domain contexts.
+2. Surface conflicts between the user's term, glossary definition, and code.
+   Sharpen vague or overloaded terms into one canonical meaning.
+3. Stress-test relationships and boundaries with concrete edge-case scenarios.
+4. Check asserted behavior against code. Let the user decide when current code
+   and intended domain truth disagree.
+5. Record a confirmed term immediately in `CONTEXT.md`, using
+   [CONTEXT-FORMAT.md](CONTEXT-FORMAT.md). Keep the glossary
+   free of implementation detail.
+6. Offer an ADR only when it meets the criteria in
+   [ADR-FORMAT.md](ADR-FORMAT.md).
+
+## Carry the model into code
+
+- Use the confirmed ubiquitous language in identifiers, tests, errors, and
+  public contracts within its bounded context.
+- Keep domain invariants in the domain model. UI, transport, persistence, and
+  orchestration layers call the model instead of reimplementing its rules.
+- Translate external schemas, persistence records, and another context's
+  vocabulary at explicit adapter seams; do not let them become the internal
+  domain model by accident.
+- Use tactical DDD patterns only when they clarify real domain rules. Reserve
+  entities, aggregates, value objects, and repositories for genuine domain concepts.
+- Return to Align when implementation reveals a domain
+  contradiction. Do not encode an unconfirmed model silently.
+
+Create the glossary or ADR directory only when there is confirmed knowledge to
+record. Domain modeling is complete when language, boundaries, invariants,
+adapters, code, and tests express the same confirmed model.
+
+---
+
+Adapted from [mattpocock/skills](https://github.com/mattpocock/skills)
+`domain-modeling` (MIT License, Copyright (c) 2026 Matt Pocock).

package/skills/grilling/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: grilling
+description: Use when resolving user-owned decisions or ambiguous architectural tradeoffs, when a decision artifact has open rows, or when the user asks to be grilled on an idea.
+---
+
+Interview the user relentlessly until you reach a shared understanding. Map the subject as a **design tree**: every decision branches into the decisions that depend on it.
+
+When a caller hands over a decision artifact, first write every consequential question into it with the answer already supported by the request or source facts, its basis, and its status; when no row is `open`, return it without interviewing.
+
+Work in **rounds**. The **frontier** is every open decision whose prerequisites are settled. Ask the whole frontier in one round, numbering each question and giving your recommended answer. Then wait for the user's answers before continuing.
+
+Format each question like this:
+
+```
+❓ **Q1 — <title>**: <question and options>
+
+➡️ <recommended answer and why>
+```
+
+Each answer reshapes the tree. Recompute the frontier before the next round. A question that still depends on another open decision belongs to a later round.
+
+Finding facts is the agent's job. Use the environment and available tools; delegate independent fact-finding only when it materially saves time. Settle observable questions by **Observe, don't ask** ([principles](../anchorloop/PRINCIPLES.md)), with a check or the `coding` prototype playbook. The decisions are the user's: put each remaining product or preference question to them and wait.
+
+When terminology or a durable architectural decision emerges, invoke `domain-modeling` at that point.
+
+The session is complete when the frontier is empty and every branch has been visited. Record each answer as `confirmed` in the caller's artifact, if any, and return the confirmed decisions to the caller.
+
+---
+
+Ported and adapted from [mattpocock/skills](https://github.com/mattpocock/skills) `grilling` and `grill-with-docs` (MIT License, Copyright (c) 2026 Matt Pocock).

package/skills/human-feedback/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: human-feedback
+description: Use when evaluating human feedback or conducting interactive UI verification.
+---
+
+# Human Feedback
+
+Turn a person's reaction to working output into an evidence-backed root cause and
+a correction made at that root. This skill owns diagnosis, not implementation.
+
+## 1. Enter
+
+Two entries:
+
+- **Detected:** a person reacts to working code, design, or documentation.
+  Invoke on the reaction itself, before answering it.
+- **Invited:** verification covers UI or a human-use scenario and the user
+  accepted a feedback pass. Name the real interface and the flows to operate,
+  then collect what the person observed.
+
+Route a crash or reproducible failure to the `coding` bug-fix playbook and a
+request for new behavior to its feature playbook. A reaction with no
+identifiable target may be venting; ask whether the user wants it investigated.
+
+**Complete when:** there is a working code, design, or documentation target the
+person wants improved.
+
+## 2. Diagnose
+
+Attend to the problem the person has, ahead of the fix they propose. Identify
+separately:
+
+- the person's observed experience and the need left unmet
+- the friction that turns that experience into negative feedback
+- the behavior, design, or documentation decision that creates the friction
+- the documented standard, best practice, or project precedent it violates
+
+Use `investigating` for substantial cross-source research. If the causal decision
+and violated standard are unsupported by evidence, classify the reaction as a
+preference rather than invent a defect.
+
+Treat justification added to a response or document as a workaround signal: it
+manages the perception of the friction while leaving its source intact. Continue
+diagnosis until the correction addresses that source and the document can state
+the expected behavior directly.
+
+**Complete when:** the chain `feedback → experience → friction → root cause →
+positive correction` is evidence-backed.
+
+## 3. Correct at the source
+
+Propose the smallest correction that removes the friction where it originates.
+Phrase its target as observable expected behavior for the person and any document
+reader. When wording creates the friction, rewrite it to state that behavior
+directly; when behavior or design creates it, correct the source and align the
+document with the result.
+
+The correction carries the source's own shape:
+
+- It lands on the causal decision, so the same friction cannot return through a
+  sibling path.
+- It matches the pattern, terminology, and layer that already govern that source.
+- A defensive guard belongs where the input is genuinely untrusted or the failure
+  is genuinely reachable; a root proven correct carries none.
+- A fallback or special case belongs where its branch is a real case of the
+  domain; a branch that exists to mask the root belongs in the root instead.
+
+Use `grilling` when viable alternatives carry a real user-owned trade-off, and
+wait for the user there. When the cause and the correction carry no such
+trade-off, state both and continue; treat later disagreement as new diagnostic
+input.
+
+## 4. Hand off
+
+Return the confirmed chain as decision input to `coding` for a source fix, or
+to `writing` for a document fix.
+
+**Complete when:** no change was requested, or the owning entry has received a
+confirmed correction target.
+
+## 5. Reflexive System Placement
+
+When feedback conveys a preference or convention rather than an isolated code bug, hand the preference to `reflecting-to-root` and any procedure change to `solid-loop`.