@gonxped31/agent-kit 0.0.0-stage → 0.3.0

package/template/dot-claude/settings.json

@@ -0,0 +1,40 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node .claude/skills/todo/scripts/todo.mjs:*)",
+      "Bash(node scripts/check.mjs:*)",
+      "Bash(node scripts/doctor.mjs:*)"
+    ],
+    "deny": [
+      "Read(./todos/**)",
+      "Edit(./todos/**)",
+      "Write(./todos/**)",
+      "Read(./todo-archive.md)",
+      "Edit(./todo-archive.md)",
+      "Write(./todo-archive.md)",
+      "Read(./*.log)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/scripts/hooks/block-big-read.mjs\""
+          }
+        ]
+      },
+      {
+        "matcher": "Bash|PowerShell",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/scripts/hooks/guard-commands.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/template/dot-claude/skills/agent-setup/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: agent-setup
+description: Where agent knowledge goes (CLAUDE.md, skills, hooks, scripts, docs, todos) and its size limits. Use when adding or changing any of them, or after a repeated mistake.
+---
+
+# Agent setup: where knowledge goes
+
+## 1. Pick the cheapest place that works
+
+| The knowledge is... | Put it in | Costs |
+| :--- | :--- | :--- |
+| A rule a machine can check | A lint rule, a git hook (`.githooks/`), a permission in `.claude/settings.json`, or a Claude hook in `scripts/hooks/` | Nothing |
+| Mechanical work done often | A script with short output: one line per problem, then OK or FAIL | Its output |
+| True for every change | The root `CLAUDE.md` | Every turn |
+| True for one folder | That folder's `CLAUDE.md` | When the agent works there |
+| A procedure for one kind of task | A skill | Its description every session; the body when used |
+| Long reference (specs, formulas, data formats) | `docs/`, listed in the root `CLAUDE.md`'s table | When read |
+| Work for later, or for when something happens | A todo with its trigger (`todo` skill) | Nothing |
+| Why a change was made | The commit message | Nothing |
+| Your own habits, true in every repo | `~/.claude/CLAUDE.md` | Every turn, in every repo |
+
+Prefer the top of the table. A written rule is a request; a check is a guarantee. When
+a rule becomes a check, keep at most one line saying why.
+
+## 2. When to add something
+
+- The same mistake twice: a rule. If a machine can check it: a check instead.
+- The same procedure explained in two sessions: a skill.
+- A command run often, with long output: a wrapper script.
+- Not before. A guardrail for something that hasn't happened yet is a todo with a
+  trigger.
+
+## 3. Size limits
+
+`node scripts/doctor.mjs` enforces them (`check` runs it).
+
+| What | Limit |
+| :--- | :--- |
+| The root `CLAUDE.md` | 800 words |
+| A folder's `CLAUDE.md` | 400 words |
+| A skill's description | 30 words, saying when to use it ("Use when ...") |
+| A `SKILL.md` | 100 lines; longer reference goes in files next to it |
+
+Change a limit in `scripts/doctor.mjs` only with the reason in the commit.
+
+## 4. Adding a skill
+
+1. Look in `.claude/skills/` first: extend a skill rather than add a near-duplicate.
+2. Write `.claude/skills/<name>/SKILL.md` with frontmatter `name` (the folder's name)
+   and `description` (what it covers, then "Use when ..."). The body is procedure:
+   steps, commands, gotchas. No history, and nothing `CLAUDE.md` already says.
+3. A script goes in the skill's `scripts/` folder. Allow it in `.claude/settings.json`
+   (`Bash(node .claude/skills/<name>/scripts/<file>:*)`), merging into the list.
+4. Don't list skills in `CLAUDE.md`: their descriptions are already in context.
+5. Run `node scripts/doctor.mjs`.
+
+## 5. Never
+
+- `@`-imports in `CLAUDE.md`: they load the whole file on every turn. Name the path in
+  backticks instead, so it's read only when needed.
+- The same fact in two places. Point to its source (the code, a doc) instead of
+  copying it: copies go stale.
+
+## 6. The kit's files
+
+agent-kit wrote the files listed in `.claude/agk.json`; change them as the repo needs.
+`agk update` brings in the kit's later changes. Where the repo changed a file, it puts
+the kit's version next to it as `<file>.kit`: merge what's new into the file, keeping
+the repo's changes, then delete the `.kit` file (`doctor` reports it until then).
+
+To reuse this repo's setup in new repos, the user can save it as a preset:
+`agk preset save <name> --list` shows what it has beyond the kit. Help them pick what's
+generic, then `--only <numbers>`.

package/template/dot-claude/skills/git/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: git
+description: Branching, committing, rebasing and merging. Use when starting a task, committing, or merging into main. One branch per task, files staged by name, main only with approval.
+---
+
+# Git: a branch per task, main only with approval
+
+`main` moves only through `node scripts/merge.mjs`, after the user approves. The
+pre-commit hook refuses commits on `main` and runs `node scripts/check.mjs --fast`. A
+Claude hook refuses `--no-verify` and bulk staging, and asks before merges, pushes and
+commands that discard work.
+
+## 1. Start every task on a new branch
+
+- `git switch -c <branch> main`. Names are short kebab-case `<area>-<topic>`, with the
+  todo ID first when there is one (`t-k7q3-route-cost`).
+- Follow-ups to the same task stay on its branch.
+- If the checkout is on a branch that isn't yours, or has changes you didn't make,
+  don't switch it. Work in a worktree in a sibling folder:
+  `git worktree add ../<repo>-<branch> -b <branch> main`.
+  - A worktree has no installed dependencies: install them there. Never link them
+    from the main checkout: removing the worktree deletes what the link points to.
+
+## 2. Commit
+
+1. `git branch --show-current` must print your branch. If it doesn't, someone switched
+   the checkout: stop and tell the user.
+2. `git status --short`, then stage what you changed **by name**. Leave out files you
+   didn't touch, and mention them.
+3. One logical change per commit. Todo changes go in the same commit as the work.
+4. If the hook fails, fix what it reports. Never get around it.
+
+Message:
+
+    <Area>: <what is now true, or what changed> (T-xxxx)
+
+    Why it was needed, and what a reader can't see in the diff.
+    Say what wasn't verified, when that matters.
+
+## 3. Stay on top of main
+
+After each commit: `git rebase main`. On a conflict, resolve it if both sides' intent
+is clear, rerun `node scripts/check.mjs`, then `git rebase --continue`. Otherwise
+`git rebase --abort` and ask.
+
+## 4. Merge into main: only with approval
+
+1. The branch is rebased onto `main`, and `node scripts/check.mjs` passes.
+2. Ask the user, stating the branch, its commits (`git log --oneline main..HEAD`) and
+   the checks run.
+3. Once approved, from the branch's checkout: `node scripts/merge.mjs <branch>`. It
+   refuses unless the tree is clean, the branch is on top of `main` and the checks
+   pass. Then it fast-forwards `main` and deletes the branch. From a worktree, it
+   prints how to remove the worktree instead.
+
+## With a remote
+
+Only if `git remote` prints one:
+- Branch from and rebase onto `origin/main`, after a `git fetch`.
+- Push your branch after each rebase: `git push -u origin <branch>` the first time,
+  then `git push --force-with-lease` (your branch only, never `main`).
+- After a merge, push `main` once the user agrees: `git push origin main`.
+
+## Never, without asking
+
+- `reset --hard`, `clean`, `checkout -- <file>`, `restore <file>`, `stash drop`,
+  `branch -D`. Undo committed work with `git revert`.
+- Rewrite `main` or force-push it.

package/template/dot-claude/skills/todo/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: todo
+description: The work queue, kept by a script. Use when working on, adding or reviewing todos, on "next todo", or when work must wait for a trigger.
+---
+
+# Todos: the queue, through its script
+
+`todos/` and `todo-archive.md` are the script's data. **Never read or edit them
+directly** (the settings deny it): go through the script, so the queue costs almost no
+tokens.
+
+## 1. Commands
+
+`T` stands for `node .claude/skills/todo/scripts/todo.mjs`, run from the repo root.
+
+| Command | What it does |
+| :--- | :--- |
+| `T next` | The best eligible item as its raw line, or `none` |
+| `T list [-p N] [--tag X] [--all]` | Eligible items; `--all` adds blocked ones, marked `*` |
+| `T show T-XXX` | The item's line, then its detail text if any |
+| `T add "text" [-p 1-3] [--dep T-A,T-B] [--size S\|M\|L] [--tag a,b]` | Creates an item; prints only the new ID |
+| `T set T-XXX [-p 1-3] [--dep T-A,T-B\|-] [--size S\|M\|L\|-]` | Changes priority, deps or size |
+| `T edit T-XXX "new text"` | Replaces the one-line description |
+| `T tag T-XXX a,b` | Replaces the tags (`-` clears them) |
+| `T detail T-XXX 'text'` or `--file path` (`-`: stdin) [`--append`] | Sets the detail text (replaces it unless `--append`) |
+| `T done T-XXX` | Archives it; prints `unblocked: ...` for items it freed |
+| `T rm T-XXX` | Removes it without archiving (obsolete) |
+| `T stats`, `T graph`, `T html [--out file]` | Counts, dependency tree, an HTML board |
+
+Line format: `ID | P | dep | size | tags | description`.
+
+- **Deps**: one ID, several comma-separated, or `-`. An item is eligible once none of
+  its deps are still open. Cycles are refused.
+- **IDs** are random, `T-` plus 4 characters (`T-k7q3`), never reused. Typing them is
+  case-insensitive.
+- **Tags**: lowercase, comma-separated, `-` for none. Use the project's own areas
+  (`setup`, `ui`, `data`...).
+- **Detail text** is deleted with the item by `done` and `rm`; the archive keeps only
+  the line. Put anything worth keeping in the code or the commit.
+- `next` picks the lowest P, then the oldest item.
+- Output is plain when piped, which is how Claude gets it: don't pass color flags.
+- **Quote text with single quotes.** Inside double quotes, Bash runs text between
+  backticks as a command, and PowerShell drops the backticks. For text with an
+  apostrophe, send it on stdin: `T detail <ID> --file - <<'EOF'`, the text, then `EOF`
+  (Bash); in PowerShell, write each apostrophe twice inside single quotes.
+
+## 2. Working a todo
+
+1. `T next`, then `T show <id>` if it may have detail text.
+2. If its size is L, or the description is vague, outline a plan and confirm it with
+   the user before editing.
+3. Do the work, focused on that one todo.
+4. `T done <id>`.
+5. `T add ...` for any follow-up work found, instead of growing the task.
+6. Report in 1-2 sentences, then stop. Don't start the next todo unless the user asked
+   for a batch.
+
+## 3. Deferred work
+
+Work that waits on something ("when X ships, do Y") is a todo, not a note in chat:
+
+    T add '<what>' --tag <area>
+    T detail <ID> 'Trigger: <X>. Do: <Y>. Why: <reason>.'
+
+The detail must stand alone: whoever picks it up won't have this conversation. Before
+finishing any task, `T list --all` and look for todos the work just triggered.
+
+## 4. Parallel worktrees
+
+The queue is built for several agents in their own worktrees. Each todo is its own file
+and IDs need no shared counter, so branches that touch different todos merge cleanly.
+`todo-archive.md` only grows, and `.gitattributes` merges it with `merge=union`, so
+both branches' `done` lines stay. The same todo changed on both sides is a real
+conflict: keep the right version by hand.