@evertonferreira96/agents 0.1.4 → 0.1.5

package/.claude/rules/adr.md

@@ -0,0 +1,42 @@
+---
+paths: ["docs/adr/**", "**/docs/adr/**"]
+---
+
+# ADRs
+
+A project's ADRs are its own. The config never ships, overwrites or deletes anything under `docs/adr/`, not even a README (`PROJECT_OWNED` in `scripts/bootstrap.mjs`). This rule is the template and the lifecycle; skills and agents point here.
+
+## Where
+
+- One file per decision: `docs/adr/NNNN-<slug>.md`. Create `docs/adr/` with the first ADR.
+- Multi-context repo (`GLOSSARY-MAP.md` at the root): context decisions live in `<context>/docs/adr/` with their own numbering; system-wide ones in `docs/adr/`.
+
+## 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`.
+
+## When and how
+
+- Skill `domain-modeling` decides whether a decision earns an ADR (hard to reverse, surprising without context, the result of a real trade-off). This rule decides how it looks and lives, and wins over that skill's `ADR-FORMAT.md`.
+- `/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.
+- `Proposed` while grilling or charting a wayfinder map; `Accepted` only with the change that implements it. An Accepted ADR changes only in its Status line; a new ADR supersedes it.
+
+## Template
+
+```markdown
+# NNNN - <title>
+
+Status: Proposed | Accepted | Partly superseded by NNNN (<which part>) | 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>
+```

package/.claude/skills/grill-with-docs/SKILL.md

@@ -25,7 +25,7 @@ After each round, append the answers to the plan's `## Grill record` (format in
 ### Glossary and ADRs
 
 - `GLOSSARY.md` (or the context glossaries a `GLOSSARY-MAP.md` lists): written by `domain-modeling` the moment a term settles, in its `GLOSSARY-FORMAT.md`. A term goes in only when the user confirms its meaning; flag where the code currently uses another name.
-- ADRs: `domain-modeling` decides **whether** a decision earns one (hard to reverse, surprising without context, the result of a real trade-off). `docs/adr/README.md` decides **how** it looks and lives, and wins over the skill's `ADR-FORMAT.md`: `NNNN-<slug>.md` with Status, Date, Context, Decision, Consequences; `Proposed` while grilling; `Accepted` only with the change that implements it; never edited once Accepted (a new one supersedes it).
+- ADRs: `domain-modeling` decides **whether** a decision earns one (hard to reverse, surprising without context, the result of a real trade-off). Rule `adr` (`.claude/rules/adr.md`) decides **how** it looks and lives, and wins over the skill's `ADR-FORMAT.md`: `NNNN-<slug>.md` with Status, Date, Context, Decision, Consequences; `Proposed` while grilling; `Accepted` only with the change that implements it; never edited once Accepted (a new one supersedes it).
 - If the decision meets an `/architect` trigger, say so: the orchestrator runs `/architect` on the proposal before it is accepted.
 
 ## Close

package/.claude/skills/orchestrate/SKILL.md

@@ -58,7 +58,7 @@ One task worktree per affected repo, inside that repo, never `git checkout` in t
 
 - L: always. M: when two competent implementers could build different things from the request. S: never.
 - Call the Skill tool with "grilling". Rounds over the design tree, every question with a recommended answer; facts come from the code or a sub-agent, decisions from the user.
-- Call the Skill tool with "domain-modeling" too, and write what `grill-with-docs` writes while the rounds run: settled terms into `GLOSSARY.md` in that skill's format, decisions that pass its three ADR tests as `Proposed` ADRs in `docs/adr/` (template and lifecycle in `docs/adr/README.md`, which wins over the skill's `ADR-FORMAT.md`). The user may start the same thing with `/grill-with-docs`.
+- Call the Skill tool with "domain-modeling" too, and write what `grill-with-docs` writes while the rounds run: settled terms into `GLOSSARY.md` in that skill's format, decisions that pass its three ADR tests as `Proposed` ADRs in `docs/adr/` (template and lifecycle in rule `adr`, `.claude/rules/adr.md`, which wins over the skill's `ADR-FORMAT.md`). The user may start the same thing with `/grill-with-docs`.
 - After each round, before asking the next one, append the answers to `## Grill record` in `docs/plans/<task>.md`: the decision, the reason in the user's own words when they add nuance, the alternatives rejected and why, and any constraint said in passing. It is the only place the grill's reasoning survives outside your window; the decisions block is its summary, not a substitute.
 - Close with the decisions block (Decisions / Deferred / Out of scope / Plan changes) and apply it to the plan. Decisions that meet an architecture trigger go to `/architect`, not silently into the plan.
 
@@ -137,7 +137,7 @@ After every parallel batch, before any verifier or next ticket.
 ## 11. ADR (L with an architecture decision)
 
 - After the first `/architect` pass, write its ADR proposal into `docs/plans/<task>.md` under Decisions.
-- At DoD, create `docs/adr/NNNN-<slug>.md` from that proposal (template in `docs/adr/README.md`) in the same diff. Grill ADRs already written as `Proposed` become `Accepted` here. This is a docs write and is yours.
+- At DoD, create `docs/adr/NNNN-<slug>.md` from that proposal (template in rule `adr`) in the same diff. Grill ADRs already written as `Proposed` become `Accepted` here. This is a docs write and is yours.
 
 ## 12. Commit
 

package/.claude/skills/project-docs/SKILL.md

@@ -278,20 +278,7 @@ Only if you actually operate this (VPS, homelab, side-project prod). Commands th
 
 ### ADR (`docs/adr/0001-<slug>.md`)
 
-Use when you chose one option and rejected others. The architecture page stays present-tense; the ADR may narrate the choice.
-
-```markdown
-# ADR 0001 - <Title>
-
-- **Status:** accepted
-- **Date:** YYYY-MM-DD
-
-## Context
-
-## Decision
-
-## Consequences
-```
+Use when you chose one option and rejected others. The architecture page stays present-tense; the ADR may narrate the choice. Template, numbering and lifecycle: rule `adr` (`.claude/rules/adr.md`), the one every skill and agent uses.
 
 ## Freshness (personal scale)
 

package/.claude/skills/wayfinder/SKILL.md

@@ -91,7 +91,7 @@ Every ticket is either **HITL** (human in the loop, worked _with_ a human who sp
 - **Grilling** (HITL): Conversation. The default case. Always call the Skill tool twice, for "grilling" and "domain-modeling".
 - **Task** (HITL or AFK): Manual work that must happen before a _decision_ can be made: nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that _does_ rather than decides, and it earns its place by unblocking a decision, not by delivering the destination. Work that touches code or infrastructure goes to the owning agent with a spike brief (AFK); anything else, or anything needing the human's credentials or accounts, is a precise checklist for the human (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on. Never write a secret into the ticket: point at where it lives.
 
-A decision that is hard to reverse, surprising without context and the result of a real trade-off also becomes a `Proposed` ADR in `docs/adr/` (skill `domain-modeling` decides whether, `docs/adr/README.md` how). The ticket links it; it becomes `Accepted` with the change that implements it.
+A decision that is hard to reverse, surprising without context and the result of a real trade-off also becomes a `Proposed` ADR in `docs/adr/` (skill `domain-modeling` decides whether, rule `adr` how). The ticket links it; it becomes `Accepted` with the change that implements it.
 
 ## Fog of war
 

package/README.md

@@ -40,7 +40,7 @@ A complete working setup for Claude Code, kept in one repo and shipped as the np
 |---|---|
 | **Agents** (10) | An orchestrator flow plus specialists: `quick`, `product`, `architect`, `api`, `web`, `app`, `infra`, `ui`, `verifier`, `security` |
 | **Skills** (39) | Workflow (orchestrate, triage, brief, review, grilling, domain-modeling, wayfinder, handoff, retro), architecture (`arch-api`, `arch-web`, `arch-app`, `arch-db`), quality (tdd, diagnosing-bugs, ponytail), design and motion |
-| **Rules** (9) | Loaded always or by path glob: git, tickets, api, web, mobile, db, ui, graphify, delivery diagram |
+| **Rules** (10) | Loaded always or by path glob: git, tickets, api, web, mobile, db, ui, graphify, adr, delivery diagram |
 | **Hooks** (8) | Deterministic guards that block what rules can only ask for: `git push`, `git add -A`, staging `.env`, the orchestrator editing code, lint and unit tests on Stop |
 | **AGENTS.md** | The shared base that Cursor and Codex read too |
 | **Updates** | A manifest of every installed file, so updates refresh what you did not touch and never overwrite what you changed |
@@ -183,7 +183,7 @@ flowchart TD
 
 **Never touched, not even with `--force`:** `CLAUDE.md`, `.claude/settings.local.json` and `.claude/agent-memory/**`.
 
-**Never shipped, so never touched either:** what the project's own work produces: `docs/plans/**` and `docs/adr/**` (except their `README.md` templates), `GLOSSARY.md`, `GLOSSARY-MAP.md` and context glossaries, `.claude/handoffs/**`. An update cannot overwrite or delete them even if a manifest lists them, and `check-catalog.mjs` fails if the config ever tries to ship one.
+**Never shipped, so never touched either:** what belongs to the project and its work: its `README.md`, everything under `docs/adr/` (no README either: the ADR template is rule `.claude/rules/adr.md`), `docs/plans/**` except the plan template `docs/plans/README.md`, `GLOSSARY.md`, `GLOSSARY-MAP.md` and context glossaries, `.claude/handoffs/**`. A `docs/adr/README.md` left by an older version is removed on update when untouched, and kept as yours when edited. An update cannot overwrite or delete them even if a manifest lists them, and `check-catalog.mjs` fails if the config ever tries to ship one.
 
 | Situation | Result |
 |---|---|
@@ -257,13 +257,12 @@ your-project/
 ├── skills-lock.json           origin and hash of every vendored skill
 ├── docs/
 │   ├── plans/README.md        plan template, one plan per task
-│   ├── adr/README.md          ADR template
 │   └── brief-template.md
 ├── scripts/                   bootstrap, check-catalog, skills-update
 └── .claude/
     ├── agents/                10 agents
     ├── skills/                39 skills
-    ├── rules/                 9 rules
+    ├── rules/                 10 rules (rule adr is the ADR template)
     ├── hooks/                 8 hooks
     ├── settings.json          hook wiring, worktree base, context limits
     ├── config-manifest.json   hash of every installed file (commit it)

package/VERSION

@@ -1 +1 @@
-0.1.4
+0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evertonferreira96/agents",
-  "version": "0.1.4",
+  "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,8 +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): GLOSSARY.md and GLOSSARY-MAP.md, docs/plans/** and docs/adr/**
-// except their README.md templates, .claude/agent-memory/**, .claude/handoffs/**. check-catalog.mjs fails if SYNC would ship one.
+// 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.
@@ -19,11 +20,15 @@ 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 the project's work produces: plans, wayfinder maps, ADRs, glossaries, agent memory, handoffs. The config only ships the two READMEs.
-export const PROJECT_OWNED = /^((?!\.claude\/)(.+\/)?GLOSSARY\.md|GLOSSARY-MAP\.md|docs\/plans\/(?!README\.md$).+|((?!\.claude\/).+\/)?docs\/adr\/(?!README\.md$).+|\.claude\/agent-memory\/.+|\.claude\/handoffs\/.+)$/;
+// 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"];
@@ -202,17 +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;
-    if (PROJECT_OWNED.test(rel)) continue; // an older config shipped it: it is the project's now, so stop tracking it, never delete it
+    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 && !isProtected(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/skills-lock.json

@@ -114,7 +114,7 @@
       "sourceType": "github",
       "sourceCommit": "49dd158",
       "skillPath": "skills/engineering/grill-with-docs/SKILL.md",
-      "note": "adapted: calls grilling + domain-modeling like upstream; adds docs/plans read-first, graphify, the Grill record, the ADR template and lifecycle of docs/adr/README.md (which wins over domain-modeling's ADR-FORMAT.md) 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": "7de372c13488f1ee96cc11cd8907b56b6809cc93eef776eeddd37de6b6cbe3fe"
     },

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,33 +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.
-
-Skill `domain-modeling` decides whether a decision earns an ADR (hard to reverse, surprising without context, the result of a real trade-off); this file decides how it looks and lives, and wins over the skill's `ADR-FORMAT.md`. In a multi-context repo (`GLOSSARY-MAP.md` at the root), context decisions live in `<context>/docs/adr/` with their own numbering and system-wide ones here.
-
-## Template
-
-```markdown
-# NNNN - <title>
-
-Status: Proposed | Accepted | Partly superseded by NNNN (<which part>) | 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>
-```