@evertonferreira96/agents 0.1.3 → 0.1.5

package/docs/plans/README.md

@@ -7,9 +7,11 @@ The newest plan is re-injected after context compaction by the post-compact hook
 Rules of the file:
 
 - Paths appear only under Scope. Decisions name modules, interfaces and contracts, never files or code.
-- Test seams are the contract between `/product`, the implementers (`tdd`) and `/verifier`: a seam not listed here is not tested, a seam listed here must be.
+- Test seams are the contract between `/product`, the implementers (`tdd`) and `/verifier`: a seam not listed here is not tested, a seam listed here must be. One row per level (e2e, entry, service, repository, unit) and public interface; each row says which criteria it proves, what it catches and what it leaves to another level. The user confirms the table at the ticket gate (`Confirmed:` line), which makes the rows the pre-agreed seams `tdd` asks for: implementers never ask, and never add a row.
+- Terms holds the domain words this plan introduces or uses differently from `GLOSSARY.md`. The user confirms them at the ticket gate and the orchestrator moves them into `GLOSSARY.md` (skill `domain-modeling`).
 - Tickets are vertical slices with `Blocked by` edges; the orchestrator works the frontier (tickets whose blockers are done) and marks Status as they land.
 - Session state is the compaction insurance: everything the orchestrator would lose with its window goes there first (skill `orchestrate` section 14).
+- Grill record is the grill on paper: the orchestrator appends to it after every round, while the conversation is still in its window, and `/product` plans from it. Nobody rewrites it later; corrections are appended. It is the last section because the post-compact hook re-injects only the first 120 lines, which must keep carrying Session state and the tickets; for the same reason Test seams, which grows with the levels, comes after Tickets.
 - A section that does not apply says `n/a` and why, so a reader knows it was considered.
 
 ## Template
@@ -48,20 +50,27 @@ Size: S | M | L
 ## Decisions
 - <decision> - <why> (modules, interfaces, schema, contracts; architect verdict and constraints)
 
-## Test seams
-| Seam | Catches | Misses | Prior art |
-|------|---------|--------|-----------|
-| S1: <public interface> | <behavior it proves> | <what it cannot see> | <existing test, or none> |
-
 ## Tickets
 <one ticket = one tracer bullet = one brief = one agent = one context window>
 | # | Ticket | Delivers | Blocked by | Agent | Paths | Seams | Status |
 |---|--------|----------|------------|-------|-------|-------|--------|
 | 1 | <title> | <end-to-end behavior, from the user's perspective> | - | /api | <globs> | S1 | todo |
 
+## Test seams
+<one row per level and public interface; default levels per size in agent `product` (step 6); levels per stack in the `arch-*` testing references>
+Confirmed: <YYYY-MM-DD at the ticket gate | pending>
+| # | Level | Seam (public interface) | ACs | Catches | Leaves to | Prior art |
+|---|-------|-------------------------|-----|---------|-----------|-----------|
+| S1 | e2e | <flow: create -> approve -> list> | AC1, AC2 | <the flow end to end, happy path and the failures that hurt most> | <rule detail: S3, S5> | <existing test, or none> |
+| S2 | entry | <POST /invoices> | AC1 | <contract, validation, authorization, error codes> | <business rule: S3> | <...> |
+| S3 | service | <CreateInvoice use case> | AC3 | <business rules and decisions, ports faked> | <SQL: S4> | <...> |
+| S4 | repository | <invoices repository adapter> | AC4 | <SQL, mapping, constraints, pagination, real database> | <-> | <...> |
+| S5 | unit | <invoice rules> | AC3 | <every edge case of the pure rule> | <-> | <...> |
+
 ## Definition of Done
 - [ ] lint, build, tests green (evidence pasted)
-- [ ] a test exists at every seam listed above
+- [ ] a test exists at every seam listed above, at its level
+- [ ] the slow suites (integration, e2e) ran in `/verifier`; the Stop hook runs only the fast one
 - [ ] diff only inside scoped paths
 - [ ] docs updated if route/job/store/integration/fallback changed
 - [ ] no secrets in diff
@@ -70,4 +79,26 @@ Size: S | M | L
 
 ## Open questions
 - ...
+
+## Terms
+<domain words this plan introduces or uses differently from GLOSSARY.md, confirmed by the user at the ticket gate and then written to GLOSSARY.md; n/a when the plan uses only glossary terms>
+- **<Term>**: <one or two sentences: what it is> _Avoid_: <synonyms> - new | conflicts with GLOSSARY.md (<entry>) | confirmed
+
+## Grill record
+<appended by the orchestrator after every grill round; never rewritten, corrections appended; n/a when no grill ran (S, or M with no open decision)>
+- Q<n> <question title>: <decision> - why: <reason, in the user's words when they add nuance>
+  - Rejected: <alternative> - <why not>
+  - Constraint: <anything said in passing that binds the work>
 ```
+
+## Wayfinder efforts
+
+Work too big and too foggy for one plan (the destination is clear, the way is not) is charted by skill `wayfinder` in its own folder, one level down so the post-compact hook never mistakes it for a task plan:
+
+```
+docs/plans/<effort>/
+  map.md                     Status, Destination, Notes, Decisions so far, Not yet specified, Out of scope
+  decisions/NN-<slug>.md     one question per file: Type, Status, Blocked by, ## Question, ## Answer
+```
+
+The map is an index: a decision lives in its ticket, and the map only gists it and links. When the map is done, the build starts as an L task with its own `docs/plans/<task>.md`, and `/product` reads the map as the source of the decisions already made.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evertonferreira96/agents",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Personal agents, rules, hooks and skills for Claude Code (portable to Cursor and Codex through AGENTS.md), installable into any project.",
   "type": "module",
   "bin": {
@@ -20,7 +20,6 @@
     "AGENTS.md",
     ".worktreeinclude",
     "docs/plans/README.md",
-    "docs/adr/README.md",
     "docs/brief-template.md",
     "scripts/bootstrap.mjs",
     "scripts/check-catalog.mjs",

package/scripts/bootstrap.mjs

@@ -7,6 +7,9 @@
 //   node scripts/bootstrap.mjs <target> --force    update --force: also overwrite files edited in the project
 //   node scripts/bootstrap.mjs --sync              inside a project bootstrapped from a local clone: pull it, then update
 // Protected (never written over): CLAUDE.md, .claude/settings.local.json, .claude/agent-memory/**
+// Project-owned (never shipped, written over or deleted, even with --force): the project's README.md, GLOSSARY.md and GLOSSARY-MAP.md,
+// docs/adr/** (no README either: the ADR template is rule .claude/rules/adr.md), docs/plans/** except its README.md template,
+// .claude/agent-memory/**, .claude/handoffs/**. check-catalog.mjs fails if SYNC would ship one.
 // .claude/config-manifest.json records the hash of every file the config installed. `update` uses it to tell a file that is
 // only outdated (overwritten) from one edited in the project (kept unless --force), and deletes files that left the config
 // only when the project copy is untouched.
@@ -17,9 +20,16 @@ import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 export const SYNC = [".claude/agents", ".claude/hooks", ".claude/rules", ".claude/skills", ".claude/settings.json", "AGENTS.md", ".worktreeinclude",
-  "docs/plans/README.md", "docs/adr/README.md", "docs/brief-template.md", "scripts/skills-update.mjs", "scripts/check-catalog.mjs", "scripts/bootstrap.mjs", "skills-lock.json"];
+  "docs/plans/README.md", "docs/brief-template.md", "scripts/skills-update.mjs", "scripts/check-catalog.mjs", "scripts/bootstrap.mjs", "skills-lock.json"];
 export const SKIP = /(^|\/)(scripts\/bin|__pycache__|node_modules|\.context-band)(\/|$)|\.pyc$/;
 export const PROTECTED = /^(CLAUDE\.md|\.claude\/settings\.local\.json|\.claude\/agent-memory\/.*)$/;
+// What belongs to the project and its work: its README, plans, wayfinder maps, ADRs, glossaries, agent memory, handoffs.
+// The config ships only the plan template (docs/plans/README.md).
+export const PROJECT_OWNED = /^(README\.md|(?!\.claude\/)(.+\/)?GLOSSARY\.md|GLOSSARY-MAP\.md|docs\/plans\/(?!README\.md$).+|((?!\.claude\/).+\/)?docs\/adr\/.+|\.claude\/agent-memory\/.+|\.claude\/handoffs\/.+)$/;
+// Files older versions shipped into a project-owned folder: update removes them when untouched, like any file that left the config,
+// and otherwise stops tracking them. docs/adr/README.md was the ADR template before it became rule adr (ADR 0013).
+export const RETIRED = new Set(["docs/adr/README.md"]);
+const isProtected = (rel) => PROTECTED.test(rel) || PROJECT_OWNED.test(rel);
 export const GITIGNORE = [".claude/worktrees/", ".claude/handoffs/", ".claude/.context-band", ".claude/.stop-verify-ran", ".claude/settings.local.json",
   ".claude/agent-memory-local/", "graphify-out/", ".claude/skills/impeccable/scripts/bin/", "__pycache__/", "*.pyc"];
 export const MANIFEST = ".claude/config-manifest.json";
@@ -45,14 +55,15 @@ export function readPackage(src = DEFAULT_SRC) {
 }
 
 // Every file the config installs, keyed by its path relative to the config root (forward slashes).
-export function configFiles(src = DEFAULT_SRC) {
+// Project-owned paths are never installed; `includeProjectOwned` lists them anyway, for check-catalog.mjs.
+export function configFiles(src = DEFAULT_SRC, { includeProjectOwned = false } = {}) {
   const files = new Map();
   for (const entry of SYNC) {
     const abs = join(src, entry);
     if (!existsSync(abs)) continue;
     for (const f of walk(abs)) {
       const rel = relative(src, f).split(sep).join("/");
-      if (!SKIP.test(rel)) files.set(rel, f);
+      if (!SKIP.test(rel) && (includeProjectOwned || !PROJECT_OWNED.test(rel))) files.set(rel, f);
     }
   }
   return files;
@@ -184,7 +195,7 @@ export function install({ src = DEFAULT_SRC, target, mode = "init", force = fals
     }
     const untouched = installed?.[rel] === have;
     if (mode === "check") { (untouched ? r.outdated : r.edited).push(rel); continue; }
-    if (mode === "update" && (untouched || force) && !PROTECTED.test(rel)) {
+    if (mode === "update" && (untouched || force) && !isProtected(rel)) {
       if (write) copyFileSync(abs, dst);
       r.updated.push(rel); next[rel] = want;
       continue;
@@ -196,16 +207,19 @@ export function install({ src = DEFAULT_SRC, target, mode = "init", force = fals
 
   for (const [rel, hash] of Object.entries(installed ?? {})) {
     if (files.has(rel)) continue;
+    const retired = RETIRED.has(rel);
+    if (PROJECT_OWNED.test(rel) && !retired) continue; // an older config shipped it: it is the project's now, so stop tracking it, never delete it
     const dst = join(target, rel);
     if (!existsSync(dst)) continue;
     const untouched = sha(dst) === hash;
     if (mode === "check") { r.obsolete.push(rel); continue; }
-    if (mode === "update" && untouched && !PROTECTED.test(rel)) {
+    if (mode === "update" && untouched && (retired || !isProtected(rel))) {
       if (write) { rmSync(dst); removeEmptyParents(target, rel); }
       r.removed.push(rel);
       continue;
     }
     if (mode === "update") r.obsoleteKept.push(rel);
+    if (retired && mode === "update") continue; // edited here: it is the project's file now
     next[rel] = hash; // keep tracking it so a later update can still remove it
   }
 

package/scripts/check-catalog.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
-// Drift checks: skills on disk vs docs/skills.md vs frontmatter vs skills-lock.json vs agents' skills: vs settings hooks.
+// Drift checks: skills on disk vs docs/skills.md vs frontmatter vs skills-lock.json vs agents' skills: vs settings hooks,
+// and no project-owned path (plans, ADRs, glossary, agent memory, handoffs) among the files the config ships.
 // Exit 1 on any error. Warnings do not fail.
 import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { configFiles, PROJECT_OWNED } from "./bootstrap.mjs";
 const errors = [], warnings = [];
 const read = (p) => readFileSync(p, "utf8");
 const fm = (p) => read(p).split("---")[1] ?? "";
@@ -37,6 +39,7 @@ for (const list of Object.values(settings.hooks ?? {})) for (const e of list) fo
   const m = /\$CLAUDE_PROJECT_DIR\/(\.claude\/hooks\/[^" ]+)/.exec(h.command ?? "");
   if (m && !existsSync(m[1])) errors.push(`settings.json: hook file ${m[1]} does not exist`);
 }
+for (const rel of configFiles(undefined, { includeProjectOwned: true }).keys()) if (PROJECT_OWNED.test(rel)) errors.push(`${rel}: project-owned path shipped by the config (scripts/bootstrap.mjs SYNC)`);
 for (const w of warnings) console.log(`warn  ${w}`);
 for (const e of errors) console.log(`ERROR ${e}`);
 console.log(`${skills.length} skills, ${rows.size} catalog rows, ${Object.keys(lock).length} lock entries: ${errors.length} error(s), ${warnings.length} warning(s)`);

package/skills-lock.json

@@ -69,6 +69,13 @@
       "skillPath": "skills/engineering/diagnosing-bugs/SKILL.md",
       "sha256": "849198df88cdb65fd0d97236604c1fca7ff2f22d2f705f9724a800d0266b118d"
     },
+    "domain-modeling": {
+      "source": "mattpocock/skills",
+      "sourceType": "github",
+      "sourceCommit": "49dd158",
+      "skillPath": "skills/engineering/domain-modeling/SKILL.md",
+      "sha256": "7b925d7b1e341a2eeae33ad68a8a8c0ab889a38ddd22a7598e4c240e5a7556a3"
+    },
     "emil-design-eng": {
       "source": "emilkowalski/skills",
       "sourceType": "github",
@@ -107,10 +114,9 @@
       "sourceType": "github",
       "sourceCommit": "49dd158",
       "skillPath": "skills/engineering/grill-with-docs/SKILL.md",
-      "note": "adapted: upstream calls grilling + domain-modeling; local version inlines glossary/ADR rules and adds docs/plans read-first, graphify and the decisions block for the orchestrator",
+      "note": "adapted: calls grilling + domain-modeling like upstream; adds docs/plans read-first, graphify, the Grill record, the ADR template and lifecycle of rule adr (.claude/rules/adr.md) (which wins over domain-modeling's ADR-FORMAT.md) and the decisions block for the orchestrator",
       "adapted": true,
-      "sha256": "4a6d8bb82e01431ecee9a13b06ccfc4b911f6ee2efcf09bc6686a8e4cee58f72",
-      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`"
+      "sha256": "7de372c13488f1ee96cc11cd8907b56b6809cc93eef776eeddd37de6b6cbe3fe"
     },
     "grilling": {
       "source": "mattpocock/skills",
@@ -253,6 +259,15 @@
       "adapted": true,
       "adaptedNote": "frontmatter only: disable-model-invocation: true (preloaded by the agents that use it)"
     },
+    "wayfinder": {
+      "source": "mattpocock/skills",
+      "sourceType": "github",
+      "sourceCommit": "49dd158",
+      "skillPath": "skills/engineering/wayfinder/SKILL.md",
+      "sha256": "9be7b478c389605a24517d27752f278933588da97a1b5921b165f455edf4c5b7",
+      "adapted": true,
+      "adaptedNote": "no issue tracker: the map is docs/plans/<effort>/map.md (with a Status line for the post-compact hook) and tickets are docs/plans/<effort>/decisions/NN-<slug>.md with Type, Status and Blocked by lines (upstream's local-markdown layout, moved under docs/plans); research tickets run as a read-only subagent with a brief instead of skill research (not vendored); prototype tickets go to /ui (skill prototype, emilkowalski) or the owning implementer in a spike worktree, never merged or pushed, since this repo's prototype is a different skill; sessions end with /clear; adds the hand-off to an L task in orchestrate when the way is clear (ADR 0012)"
+    },
     "writing-for-agents": {
       "source": "mattpocock/skills",
       "sourceType": "github",

package/templates/CLAUDE.project.md

@@ -27,7 +27,7 @@
 - Skills: `.claude/skills/` (catalog and wiring: docs/skills.md)
 - Architecture skills: arch-api (NestJS), arch-web (Next.js), arch-app (Expo), arch-db (Postgres/MySQL; loaded by rule db.md)
 - Plans: `docs/plans/` (template in docs/plans/README.md)
-- ADRs: `docs/adr/` (template and numbering in docs/adr/README.md)
+- ADRs: `docs/adr/` (template and numbering in rule `.claude/rules/adr.md`; the folder is yours, the config never writes to it)
 - Brief template: skill `brief` (`docs/brief-template.md` points there)
 - Vendored skills: origins in `skills-lock.json`; check upstream with `node scripts/skills-update.mjs`
 - Decisions about this repo: `docs/adr/`; changes: `CHANGELOG.md`

package/docs/adr/README.md

@@ -1,31 +0,0 @@
-# ADRs
-
-One file per architecture decision: `docs/adr/NNNN-<slug>.md`.
-
-## Numbering
-
-- `NNNN` is 4 digits, zero-padded, next after the highest existing number (`0001`, `0002`, ...). Never reuse a number.
-- `<slug>` is lowercase kebab-case of the title.
-- ADRs are immutable once Accepted. To change a decision, write a new ADR and set the old one to `Superseded by NNNN`.
-
-## Flow
-
-`/architect` returns an ADR proposal, the orchestrator copies it into `docs/plans/<task>.md`, and at DoD creates the ADR file in the same diff as the change.
-
-## Template
-
-```markdown
-# NNNN - <title>
-
-Status: Proposed | Accepted | Superseded by NNNN | Deprecated
-Date: YYYY-MM-DD
-
-## Context
-<forces, constraints, the problem; link the plan>
-
-## Decision
-<what we do, in present tense>
-
-## Consequences
-<what gets easier, what gets harder, rejected alternatives and why>
-```