@sayansr26/agent-os 0.5.0

package/plugins/agent-os/skills/init/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: init
+description: Set up or repair this project's Claude Code context layer. Audits what is already there — CLAUDE.md size, whether .claude/rules/ files are path-scoped, dangling hooks, legacy memory-bank or serena stores, auto-memory state, and machine-level problems like user-scope agents shadowing plugin ones — then creates or migrates what is missing. Use for "set up agent-os", "agent-os init", "initialise this project", "bootstrap my context setup", "migrate off memory-bank", "my CLAUDE.md is too big", or when starting work in a repo with no setup.
+---
+
+# Memory bootstrap
+
+Bring any repository up to the standard context layout, without inventing facts
+and without ballooning what loads every session.
+
+The layout this skill converges on:
+
+| Tier | Lives in | Startup cost | Holds |
+|---|---|---|---|
+| Always-loaded | `CLAUDE.md`, ≤200 lines | small, fixed | Only what is true in *every* session |
+| On-demand | `.claude/rules/*.md` with `paths:` frontmatter | **zero** | Durable facts scoped to some files |
+| Self-writing | auto memory (`~/.claude/projects/<repo>/memory/`) | index only | Corrections, preferences, decisions |
+| Explored | `.claude/agent-memory/feature-cartographer/` | **zero** (subagent context) | How each feature is actually built |
+| Task state | the project's own vault / handoff file | zero (read selectively) | What is in flight right now |
+
+The principle the whole layout serves: **storing a fact and loading a fact are
+different acts.** Anything that makes them the same act — a handbook CLAUDE.md,
+a memory-bank read at every startup, a rules file with no `paths:` — is the bug.
+
+## `$ARGUMENTS`
+
+| Argument | Do |
+|---|---|
+| *(none)* | The full pass: audit, then route by MODE |
+| `audit` | Run the audit and report. Change nothing. |
+| `settings` | The settings and permissions pass only — read `~/.claude/settings.json` and the project's, report what is set, and propose changes. See below. |
+
+Related skills: `/agent-os:map` builds the architecture map, `/agent-os:memory`
+inspects and repairs what the project remembers.
+
+## Step 1 — Run the audit
+
+One call. Do not rediscover this with a dozen Read and Grep round trips — the
+checks are deterministic and the script does all of them at once:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/skills/init/scripts/audit.mjs"
+```
+
+Pass a path as the first argument to audit a project other than the working
+directory. It is read-only and exits 0 even when checks fail, so a partial audit
+still reaches you.
+
+It reports: always-loaded files and their line counts, whether every
+`.claude/rules/` file is path-scoped, whether each hook's target exists, legacy
+stores (`memory-bank/`, `.serena/memories/`, cursor and windsurf rules, memory-ish
+MCP servers), per-agent memory health, the machine layer (`~/.claude` CLAUDE.md,
+shadowing agents or skills, a duplicate session-resume hook, permissions
+posture), the startup byte and token cost, and a ranked finding list.
+
+**Show the output to the user before you change anything.** Do not restructure a
+repo you have only just opened.
+
+## Step 2 — Route by MODE
+
+The audit ends with a `MODE` line. It decides what this run is for:
+
+| MODE | What it means | Do |
+|---|---|---|
+| `TOO-EARLY` | Barely any source | **Build nothing.** Tell the user to write code, run Claude Code's `/init`, and come back. A layer over an empty project is invented conventions. |
+| `ESTABLISH` | Real code, no context layer | `references/establishing.md` — build the layer *from the code* |
+| `MAP` | Layer healthy, never mapped | `references/establishing.md`, "Map the architecture" |
+| `MIGRATE` | Layer exists, has problems | fix the findings; `references/migrating.md` for legacy stores |
+| `MAINTAIN` | Healthy and mapped | report and stop |
+
+`ESTABLISH` and `MAP` are the modes that make a later request like *"change the
+login flow from email to OTP"* execute from known structure instead of
+rediscovering the codebase. `references/changing-a-feature.md` is that workflow —
+point the user at it once the layer exists.
+
+## Step 3 — Act on the findings
+
+Each finding routes to one place. Load only what the audit actually surfaced:
+
+| Finding | Read |
+|---|---|
+| `MODE ESTABLISH` or `MODE MAP` | `references/establishing.md` |
+| user asks how to change an existing feature | `references/changing-a-feature.md` |
+| legacy store found; CLAUDE.md over budget | `references/migrating.md` |
+| rule without `paths:`; no rules layer yet; CLAUDE.md to trim | `references/writing-rules.md` |
+| `defaultMode` auto-approves with an empty `deny` | `references/git-permissions.md` |
+| LSP plugin recommended; checked-in generated dirs | `references/establishing.md`, "Stop Claude reading what it should not" |
+| hook target missing | delete the hook entry, or restore the script — say which |
+| shadowing agent or skill in `~/.claude` or `.claude/agents/` | the user removes the standalone copy; a plugin cannot |
+| unindexed or near-duplicate agent memory topic files | merge into the best-named file, delete the rest, rebuild `MEMORY.md` as one line per file |
+| project CLAUDE.md refers to a `~/.claude/CLAUDE.md` that is absent | the user creates it or drops the reference |
+
+Findings on the machine layer are the user's to fix — a plugin cannot write
+`~/.claude`. Hand over the exact change rather than attempting it.
+
+## Step 4 — Verify by re-running
+
+Run the audit again and show the before and after: finding count, startup bytes,
+token estimate. Do not declare success on vibes — the script already produces the
+numbers, so quote them.
+
+## The settings pass
+
+The audit already reads both settings files and reports `defaultMode`, the deny
+list, hook registrations and shadowing. To act on it:
+
+1. **Show what is set** — project `.claude/settings.json` and `~/.claude/settings.json`,
+   side by side, so the user can see which rules exist only in this project and
+   therefore vanish in every other one.
+2. **Propose, do not apply.** Write out the exact JSON block and ask. This is the
+   one place where acting first is wrong: `permissions.deny` is the guardrail on
+   your own behaviour, and a skill that edits its own guardrails without being
+   asked is exactly the thing the setting exists to prevent. Apply only after an
+   explicit yes, and never widen an existing deny list without pointing out what
+   it would stop blocking.
+3. **What to propose**, when the audit flagged it:
+   - git write protection — `references/git-permissions.md` has the rule set
+   - `Read` deny rules for checked-in generated or vendored paths
+   - a code intelligence plugin for the detected language
+   - `claudeMdExcludes` in a monorepo where other teams' files load
+
+Anything under `~/.claude/` affects every project on the machine. Say so before
+proposing it, and prefer the project's own settings file when the rule is really
+about this project.
+
+## What this skill will not do
+
+- It will not write facts it has not verified in the repo. An invented rule is
+  worse than a missing one, because it will be trusted.
+- It will not delete a legacy store before its content has landed.
+- It will not add a memory MCP server. A knowledge graph solves retrieval over
+  unstructured memory; the common failure is that nothing was *written*, which a
+  graph does not fix and which the cartographer's memory does — with no database,
+  no embedding step, and no tokens in the main window.

package/plugins/agent-os/skills/init/references/changing-a-feature.md

@@ -0,0 +1,104 @@
+# Changing an existing feature
+
+The workflow for a request like *"change the login flow from email to OTP"*, or
+any change to code that already exists.
+
+The point is that **no step re-reads the codebase from scratch**. Structure comes
+from the map, conventions come from the rules, and only the files actually being
+changed get opened.
+
+## Do not start by reading code
+
+The instinct is to grep for `login` and start opening files. That costs a lot of
+context, finds the obvious call sites and misses the non-obvious ones, and
+produces a change written in the model's default style rather than this
+codebase's.
+
+## Step 1 — Ask the cartographer how it is built
+
+> use the feature-cartographer: how is the login flow currently implemented?
+
+It reads `_architecture.md` and any existing map first, explores only what is
+missing, and returns about forty lines in **its** context, not yours:
+
+```
+Entry:      src/features/auth/LoginPage.tsx:24 (route /login)
+Renders:    LoginForm.tsx, OtpDialog.tsx (already exists — used by password reset)
+State:      authSlice — also read by the session provider
+Network:    services/auth.api.ts -> POST /auth/login, POST /auth/refresh
+Gated by:   nothing; /login is public
+
+Blast radius
+- useAuth() — imported by 14 files outside this feature
+- authSlice.login — dispatched from 3 places
+
+To change the login method, edit: services/auth.api.ts, LoginPage.tsx, authSlice.ts
+Watch out
+- OtpDialog already exists for password reset; reuse it rather than writing one
+```
+
+That last line is the whole argument for this step. A cold grep for `login` would
+not have found the OTP dialog that already exists — and you would have built a
+second one.
+
+## Step 2 — Find the nearest precedent
+
+Before designing anything, ask what this codebase already did that resembles the
+change. An OTP flow somewhere else, a second auth method, a similar
+service-and-slice pair. The cartographer's map will usually name it.
+
+Matching an existing precedent is almost always better than a cleaner design that
+matches nothing else in the repository.
+
+## Step 3 — Let the rules load themselves
+
+The path-scoped rules under `.claude/rules/` load when a matching file is
+touched. Touching `src/features/auth/` brings in the feature rules; touching a
+service brings in the service conventions. You do not need to fetch them, and you
+should not paste them into the prompt.
+
+If the rules layer does not exist yet, stop and read `establishing.md`. Making a
+structural change to a codebase whose conventions are not written down means
+inventing them in the diff.
+
+## Step 4 — Build against the precedent
+
+Dispatch `builder` with the cartographer's output, the precedent, and the files
+to change — not with the original one-line request. An agent that receives
+"change login to OTP" starts from nothing; one that receives the map, the
+precedent and the file list starts where step 1 finished.
+
+`builder` reads `CLAUDE.md` and the matching rules before writing, and matches the
+nearest existing example for anything the rules do not cover.
+
+## Step 5 — Review against the rules, not against taste
+
+`reviewer` checks the diff against this project's documented rules first, then
+correctness, security and the seams. A violation of a written project rule is the
+highest-severity finding available, because the project already decided.
+
+## Step 6 — Update the map, in the same turn
+
+**The map is now stale.** The login flow no longer works the way its topic file
+says it does.
+
+Re-dispatch the cartographer to update the topic file for the area you changed,
+or the change silently poisons the next question about it. A map that was right
+last week and is wrong today is worse than no map, because it will be trusted.
+
+This is the step that gets skipped. Treat it as part of the change, not as
+follow-up work.
+
+## What this costs
+
+Roughly, for a feature change in a large codebase:
+
+| | Cold | With the map |
+|---|---|---|
+| Finding how it works | 15–30 file reads in your context | ~40 lines returned from a subagent |
+| Finding the conventions | re-derived, inconsistently | loaded automatically by path |
+| Finding the precedent | usually missed | named in the map |
+| Second change to the same area | the same cost again | near zero |
+
+The first question about an area is cheaper. Every question after it is close to
+free. That is the point of writing the map down.

package/plugins/agent-os/skills/init/references/establishing.md

@@ -0,0 +1,128 @@
+# Establishing a context layer from an existing codebase
+
+Read this when the audit reports `MODE ESTABLISH` or `MODE MAP`: there is real
+code but no context layer, or a layer but no architecture map.
+
+The goal is not a smaller `CLAUDE.md`. The goal is that a request like *"change
+the login flow from email to OTP"* can be executed from **known structure and
+known conventions**, instead of rediscovering the codebase from scratch every
+time. Smaller context is a consequence, not the objective.
+
+## The one rule
+
+**Everything you write must be something you observed in this repository.** Not
+something you know about React, or Django, or how projects like this usually
+work. If you did not open the file, it does not go in.
+
+An invented convention is worse than a missing one, because the next agent will
+follow it and the reviewer will enforce it.
+
+## Step 1 — Let Claude Code write the first draft
+
+Do not hand-write `CLAUDE.md` from nothing. Claude Code's own `/init` explores
+the codebase and generates a starting file; `/doctor` trims a checked-in one and
+migrates guidance out of it. Use those first, then build on the result.
+
+Tell the user to run `/init` if no `CLAUDE.md` exists, and take what it produces
+as the starting point. `agent-os` adds the layers `/init` does not: the
+architecture map, conventions extracted from real code, and path-scoped rules.
+
+## Step 2 — Map the architecture
+
+Dispatch `feature-cartographer` with an explicit system-level brief, not a
+feature question:
+
+> Map this codebase at the system level. Produce `_architecture.md`: the stack
+> and versions, the layers and what each owns, where a request enters and how it
+> reaches data, the state management, the network edge, the auth and permission
+> model, the build and run commands, and the three or four files a newcomer must
+> read first. Name real files. Say what you could not determine.
+
+It writes `_architecture.md` into its own memory and indexes it in `MEMORY.md`.
+That file becomes the starting point for every later "how is X built" question —
+the cartographer reads it before exploring, so the second question about any area
+is cheap and the first is cheaper than cold.
+
+Re-dispatch this when the architecture actually changes, not on a schedule.
+
+## Step 3 — Extract conventions from real code
+
+This is the part that makes a change follow the existing style rather than the
+model's defaults. For each kind of thing the codebase contains — a service, a
+component, a route, a migration, a test — do this:
+
+1. **Find at least three independent examples.** Glob for the shape, pick three
+   written at different times if you can tell.
+2. **Read them.** Not outlines. The convention lives in the details: how errors
+   are handled, where validation sits, what gets logged, how state is reached,
+   how the network is called, what the file is named and where it lives.
+3. **Write down only what is consistent across all three.** One file is a sample.
+   Two is a coincidence. Three that agree is a convention.
+4. **Note what varies.** If two services handle errors differently, that is not a
+   convention — it is drift. Say so; do not pick a winner on the codebase's
+   behalf.
+5. **Record where you saw it.** Name the files the pattern came from. A future
+   reader can re-check a cited rule; an uncited one rots.
+
+The highest-value things to capture are the ones a newcomer gets wrong:
+
+- **Registration sites.** Where does a new route, nav item, feature flag or
+  migration have to be registered, and is that where the docs say? Check.
+- **The seam.** How does this codebase talk to its backend, and what wraps it?
+- **The gate.** How is a feature permitted — role, flag, config, middleware?
+- **The thing that looks optional but is not.** A required call in every handler,
+  an index that must be added, a twin file that must be updated together.
+
+## Step 4 — Write the rules
+
+Group by **what the reader is touching**, not by topic. Each file gets `paths:`
+frontmatter narrow enough that it is absent most of the time.
+
+```markdown
+---
+paths:
+  - "src/features/**"
+  - "src/pages/**"
+---
+
+# Working inside a feature
+
+Services export one function per endpoint and go through the shared client
+wrapper, never a bare fetch. Errors surface as a typed result, not a throw.
+Verified across three services; see the ones named in `_architecture.md`.
+```
+
+Dense agent notes, not prose. Invariants and gotchas. Skip anything a `ls` or a
+grep answers — that is rule 2 in the README and it applies hardest here.
+
+## Step 5 — Stop Claude reading what it should not
+
+Two settings with a large effect on how much gets read, both worth proposing:
+
+- **Code intelligence.** If the audit named an LSP plugin, install it:
+  `/plugin install typescript-lsp@claude-plugins-official` (or the one for your
+  language). Claude then jumps to a definition and finds references through the
+  language server instead of scanning the tree. For "where is login handled and
+  what calls it", this is the single biggest win available.
+- **`Read` deny rules** for checked-in generated or vendored code:
+
+  ```json
+  { "permissions": { "deny": [
+      "Read(./**/dist/**/*)", "Read(./**/generated/**/*)", "Read(./**/vendor/**/*)"
+  ] } }
+  ```
+
+  `.gitignore`d paths are already excluded from search; these cover the ones that
+  are committed.
+
+In a monorepo, also consider per-directory `CLAUDE.md` files so each package's
+conventions load only when Claude reads there.
+
+## Step 6 — Verify
+
+Re-run the audit. `MODE` should move to `MAINTAIN`. Show the user the before and
+after: finding count, startup bytes, and what got mapped.
+
+Then prove it works on a real question. Ask the cartographer something you
+already know the answer to, and check it. A map that is confidently wrong is
+worse than no map, and this is the cheapest moment to find out.

package/plugins/agent-os/skills/init/references/git-permissions.md

@@ -0,0 +1,118 @@
+# Git permission rules — block writes, keep reads
+
+A `permissions.deny` set that blocks every git command which changes the
+repository, while leaving read-only inspection (`status`, `log`, `diff`, `show`,
+`blame`, `rev-parse`, `ls-files`, `describe`, `grep`, `shortlog`, …) available.
+
+Paste into `~/.claude/settings.json` for every project, or a project's
+`.claude/settings.json` for one.
+
+```json
+{
+  "permissions": {
+    "deny": [
+      "Bash(git -C*)",
+      "Bash(git -c*)",
+      "Bash(git --git-dir*)",
+      "Bash(git --work-tree*)",
+      "Bash(git --exec-path*)",
+
+      "Bash(git add *)",
+      "Bash(git am *)",
+      "Bash(git apply *)",
+      "Bash(git bisect *)",
+      "Bash(git branch *)",
+      "Bash(git checkout *)",
+      "Bash(git cherry-pick *)",
+      "Bash(git clean *)",
+      "Bash(git clone *)",
+      "Bash(git commit *)",
+      "Bash(git config *)",
+      "Bash(git fast-import *)",
+      "Bash(git filter-branch *)",
+      "Bash(git gc *)",
+      "Bash(git init *)",
+      "Bash(git merge *)",
+      "Bash(git mv *)",
+      "Bash(git notes *)",
+      "Bash(git prune *)",
+      "Bash(git pull *)",
+      "Bash(git push *)",
+      "Bash(git rebase *)",
+      "Bash(git reflog *)",
+      "Bash(git remote *)",
+      "Bash(git repack *)",
+      "Bash(git replace *)",
+      "Bash(git reset *)",
+      "Bash(git restore *)",
+      "Bash(git revert *)",
+      "Bash(git rm *)",
+      "Bash(git stash *)",
+      "Bash(git submodule *)",
+      "Bash(git switch *)",
+      "Bash(git symbolic-ref *)",
+      "Bash(git tag *)",
+      "Bash(git update-ref *)",
+      "Bash(git worktree *)"
+    ]
+  }
+}
+```
+
+## Why the first five entries matter
+
+Without them the rest of the list is decorative. Claude Code matches a Bash rule
+literally on the words before the first `*`, so `Bash(git commit *)` does **not**
+match any of these:
+
+```
+git -C . commit -m "..."
+git -c user.email=x@y commit -m "..."
+git --git-dir=.git --work-tree=. commit -m "..."
+```
+
+`git -C` and `git -c` run any subcommand with a different directory or config,
+which walks straight past a per-subcommand list. Denying the flag forms outright
+closes that. The cost is that `git -C <path> status` is blocked too — `cd` there
+instead.
+
+## What this does not stop
+
+**Quoting.** `git 'commit' -m "..."` does not match `Bash(git commit *)` either,
+and there is no pattern that enumerates every quoting variant. Treat this list as
+a strong guardrail against an agent doing the wrong thing by default, not as a
+boundary against one determined to get around it.
+
+If you need a hard boundary, there are two options, and both cost you read-only
+git:
+
+- `"deny": ["Bash(git:*)"]` — one rule, matches every invocation including the
+  flag and quoted forms.
+- A `PreToolUse` hook that parses the command itself and exits non-zero.
+
+Deny cannot carry allow exceptions — deny is evaluated first and always wins — so
+you cannot pair a broad rule with `allow: ["Bash(git status *)"]` to get both.
+
+## Judgment calls in this list
+
+- **`git fetch` is allowed.** It writes remote-tracking refs but cannot touch the
+  working tree, index, HEAD, or a local branch, and blocking it breaks legitimate
+  inspection of remote state. Add `"Bash(git fetch *)"` if you disagree.
+- **`git reflog` is denied** because `reflog expire` and `reflog delete` destroy
+  recovery history. That also blocks the read form; `git log -g` is an
+  unrestricted equivalent.
+- **`git tag` is denied** wholesale, which also blocks listing tags. Use
+  `git for-each-ref refs/tags` to list them.
+
+## How the rules behave
+
+- A deny rule matches inside compound commands, subshells, command substitution
+  and control-flow bodies, so `cd /tmp && git clean -f` and `echo "$(git reset
+  --hard)"` are both blocked.
+- A deny rule matches past a leading environment assignment, so
+  `GIT_AUTHOR_NAME=x git commit` is blocked.
+- `Bash(git commit *)` and `Bash(git commit:*)` are equivalent; the `:*` suffix is
+  just another way to write a trailing wildcard. It only works at the end of a
+  pattern — `Bash(git:* push)` treats the colon as a literal character.
+- A trailing `* ` with a space also matches the bare command, so
+  `Bash(git push *)` blocks `git push` on its own.

package/plugins/agent-os/skills/init/references/migrating.md

@@ -0,0 +1,43 @@
+# Migrating an existing setup
+
+Read this when the audit reports a legacy store, or a CLAUDE.md over budget.
+
+## Preserve before you delete
+
+Content in a legacy store is usually real, hard-won knowledge. It is the
+*loading* that was wrong, not the writing. Never delete a legacy store until its
+content has landed somewhere. For each fact in it, ask:
+
+- **True in every session, for every file?** → `CLAUDE.md`. Rare — build commands,
+  the hard rules, the definition of done, how to verify.
+- **Durable but scoped to some files?** → a `.claude/rules/` file with `paths:`.
+  This is where most of it goes.
+- **Derivable from the code?** → delete it. Directory tours, dependency lists,
+  architecture overviews, file inventories. The cartographer regenerates these on
+  demand and cannot go stale the way a written copy does.
+- **About the user, or a correction, or a decision?** → leave it; auto memory takes it.
+- **About work in flight?** → the task vault.
+
+Back up what you replace (`CLAUDE.md.pre-migration.bak`) and tell the user where
+the backup is.
+
+
+## Confirm the shared pieces are active
+
+These ship with the `agent-os` plugin, so normally there is nothing to install —
+just confirm they are working and wire up anything project-specific:
+
+- **`feature-cartographer`** answers "how is X built" and accumulates a per-repo
+  map under `.claude/agent-memory/feature-cartographer/`. Decide with the user
+  whether that map is committed (useful shared knowledge for a team) or ignored
+  (add `.claude/agent-memory/` to `.gitignore`). Check it appears in `/context`
+  under Custom Agents.
+- **The session-resume hook** prints the where-you-left-off block at every
+  session start. If this project keeps a handoff note at a path the hook does not
+  already check, say so — the candidate paths are listed in the hook source, and
+  changing them is a plugin change, not a project one.
+
+If an agent or the hook is missing, the plugin is not loaded. Say so and point
+the user at `/plugin` rather than writing a project-local copy — a per-project
+fork of a shared tool is how the two silently drift apart.
+

package/plugins/agent-os/skills/init/references/writing-rules.md

@@ -0,0 +1,50 @@
+# Writing rules files and trimming CLAUDE.md
+
+Read this when the audit reports an over-budget CLAUDE.md, a rule without
+`paths:`, or when you are creating the rules layer from scratch.
+
+## Write the rules files
+
+Group by **what the reader is touching**, not by topic. A rule earns its keep
+when its `paths:` are narrow enough that it is absent most of the time.
+
+```markdown
+---
+paths:
+  - "src/features/**"
+  - "src/pages/**"
+---
+
+# Working inside a feature
+...
+```
+
+Rules of thumb:
+
+- Every rule file gets `paths:`. No exceptions — an unscoped rule belongs in
+  CLAUDE.md or nowhere.
+- If two rules would always match together, they are one rule.
+- If a rule matches all of `src/**`, it had better be the single most important
+  convention in the repo. One such rule is defensible; three is a handbook.
+- Dense agent notes, not prose docs: invariants, terse bullets, the non-obvious.
+  Skip rationale and examples unless they prevent a likely mistake.
+- A gotcha is worth more than a description. "X is at Y" is derivable; "X looks
+  like it is at Y but is actually at Z, and the project's own docs say otherwise"
+is not.
+
+## Trim CLAUDE.md
+
+Target ≤200 lines; aim for ~150. Keep:
+
+- How to run, build and verify — and whatever the user does *not* want run
+  automatically.
+- The hard rules, one line each, with a pointer to the rule file for detail.
+- The definition of done.
+- What automations exist (hooks, subagents, skills, MCP), briefly.
+- A table of the rule files and what each covers, so the layout is discoverable.
+
+Cut: directory tours, dependency lists, architecture narration, anything a
+`ls`/`Grep` answers, anything a rule file now owns, and any instruction that is
+really a personal preference (that belongs in `~/.claude/CLAUDE.md`, once,
+globally — not re-typed per project).
+