@abblor/agent-os

Skills, workflows, memory, specs, constitution, hooks, and rules for AI coding agents (Claude Code, GitHub Copilot CLI, Cursor, etc.) working across abblor_repos projects. Think of it as the shared "operating system" for how AI agents behave in these codebases:

• rules (kernel policy) — non-negotiable laws every agent must follow.
• skills (drivers) — methodology and stack-specific know-how agents load per task.
• memory / hooks (runtime services) — self-improvement logging and lifecycle enforcement.
• specs / constitution — the shared documentation templates and the universal rules every abblor_repos project inherits.

See NOTICE.md for attribution: this package bundles and adapts MIT-licensed content from obra/superpowers and Sahir619/fable-method, alongside an internally-authored extended skill library. Licensed under MIT. See CHANGELOG.md for release history.

What's inside

agent-os/
  skills/          39 skills: core methodology (superpowers), extended
                   stack skills (web-ui, api-design,
                   docker-expert, ...) + the fable-method family
                   (fable-method, fable-loop, fable-judge, fable-domain),
                   plus SKILL_INDEX.template.md and consolidation-manifest.json
  workflows/       *.template.md workflow scripts (build-feature, check-docker)
  constitution/    constitution.md — universal, non-negotiable rules
  rules/           rules.template.md — thin per-project rules layer
  specs/           app-blueprint.template.md — SRS/Architecture/Features
                   documentation templates
  memory/          lessons-template.md — cross-project lessons log format
  hooks/
    agent/         agent lifecycle hook conventions + reference configs
                    (Claude Code SessionStart/PreToolUse, etc.)
    git/           real git hooks (commit-msg, pre-push) enforcing the
                    constitution regardless of which agent tool is used
  ci/              enforce-commit-msg.template.yml — GitHub Actions
                    CI-level backstop for the constitution's Conventional
                    Commits + Zero AI Watermark Policy rules
  test/            automated tests for bin/cli.js (npm test)

Adopting this package in a project

1. Install:

   npm install --save-dev @abblor/agent-os

2. Link the shared, generic content (skills, hooks, constitution) into your repo's .agents/:

   npx agent-os link

   This creates symlinks, and also runs automatically via this package's own postinstall script on every npm install — so skills/constitution/ git hooks stay in place with zero manual steps, from the very first clone onward. It never touches real (non-symlink) files, so it's safe to run repeatedly and won't clobber a local project-specific skill (e.g. .agents/skills/<Project>-Domain-Expert/) living alongside the symlinked ones.

   Version pinning policy: many abblor_repos projects set save-exact=true in .npmrc, which makes npm install --save-dev @abblor/agent-os write an exact version pin (e.g. "0.1.2", no ^) rather than a caret range. With an exact pin, npm update will not pick up new agent-os releases — that's intentional: a shared skills/constitution/hooks package changing the rules every agent follows deserves a deliberate, reviewed version bump, not a silent auto-update. To pick up a new release, explicitly run npm install @abblor/agent-os@latest (or a specific version), review what changed in CHANGELOG.md, then commit the package.json/package-lock.json bump through your normal PR process — the same as any other dependency update. Don't "fix" the pin to ^ to make updates automatic; that defeats the point.

3. Scaffold your project's own customized files (one-time):

   npx agent-os init

   Interactively prompts for your project name/slug/domain (or pass --name, --slug, --domain, --yes for non-interactive use) and writes .agents/rules.md, .agents/app-blueprint.md, .agents/skills/SKILL_INDEX.md, .agents/workflows/*.md, and .agents/tasks/lessons.md with placeholders filled in. Never overwrites existing files — safe to re-run after adding new workflow templates upstream.

4. Point your IDE/agent tooling at .agents/: ensure .cursorrules, .github/copilot-instructions.md, AGENTS.md, or equivalent instructs agents to read /.agents/constitution/constitution.md, /.agents/rules.md, /.agents/app-blueprint.md, and /.agents/skills/SKILL_INDEX.md before starting any task (this text is provided ready-made in constitution.md §0 — copy it in).

5. Git hooks are installed automatically — npm install already ran the commit-msg and pre-push hooks into .git/hooks/ as part of step 2's postinstall step (as long as .git/ already existed at install time and no --ignore-scripts flag was used). Verify with:

   ls -la .git/hooks/commit-msg .git/hooks/pre-push

   If either is missing (e.g. you ran git init after npm install, or used --ignore-scripts), just re-run npx agent-os link — or install manually:

   ln -sf ../../.agents/hooks/git/commit-msg .git/hooks/commit-msg
   ln -sf ../../.agents/hooks/git/pre-push .git/hooks/pre-push

   Neither ever clobbers a real (non-symlink) hook already installed by husky, lefthook, or your own scripts — it warns and leaves those alone.

   Caveat: some AI tools add their own Co-authored-by: <Tool Name> trailer to every commit by default (e.g. GitHub Copilot CLI, unless told otherwise). The Zero AI Watermark Policy's forbidden-phrase list includes tool names like copilot/claude/chatgpt, so a commit with such a trailer will be blocked by this hook once installed. Either configure your AI tool to omit that trailer in repos using this hook, or don't install the hook if you rely on it for transparency/audit purposes — the two are currently incompatible.

6. Add the commit-message CI backstop (optional, opt-in — only add this once your existing commit history already complies, since it will fail PRs on any commit that doesn't):

   npx agent-os init --with-ci

   Scaffolds .github/workflows/enforce-commit-msg.yml, which enforces Conventional Commits and the Zero AI Watermark Policy on every commit in a pull request — a CI-level check that can't be bypassed the way the local git hook above can (e.g. git commit --no-verify).

7. Fill in .agents/rules.md § 1 with any rules unique to your project that don't belong in the shared constitution.

Updating

If your package.json uses a caret range (^0.1.2), npm update @abblor/agent-os picks up new patch/minor releases automatically, and postinstall re-links everything on the next npm install.

If your project pins an exact version (common when .npmrc has save-exact=true, which several abblor_repos projects already set), npm update is a no-op for this package by design — that's the point of an exact pin, not a bug. To take a new release:

npm install @abblor/agent-os@latest   # or a specific version
npx agent-os link                     # re-run in case postinstall didn't (e.g. --ignore-scripts)
npx agent-os check                    # confirm every new skill is routed in your SKILL_INDEX.md

link also prunes stale symlinks for skills retired by a package upgrade, but only when the link target is a direct child of this installed package's own skills/ directory. Real project directories and project-owned symlinks are never removed. Because init never overwrites a consumer's customized SKILL_INDEX.md, follow the release migration notes for route renames and run agent-os check afterward.

A new release can add skills. link will symlink them in, but each project keeps its own .agents/skills/SKILL_INDEX.md — the template in this package is scaffolding for init, not a live symlink — so a newly added skill is invisible to agents until you add a routing row for it. That is what agent-os check is for; wire it into CI (see below) so the gap fails a build rather than going unnoticed.

Verifying a consumer with agent-os check

npx agent-os check          # exits non-zero if the wiring is broken

It fails the build when:

• one of the four mandatory files (constitution/constitution.md, rules.md, app-blueprint.md, skills/SKILL_INDEX.md) is missing or unreadable
• any symlink under .agents/ dangles — the state of a fresh clone before npm install, or after npm install --omit=dev
• a skill is installed in .agents/skills/ but never mentioned in SKILL_INDEX.md, so no agent can ever load it
• SKILL_INDEX.md routes to a skill (or workflow path) that isn't there

It warns, without failing, when a skill is catalogued in the index but not cited by any "Required Skills" row, since agents match tasks against the routing tables.

Add it to CI next to your lint step:

- run: npx agent-os check

Review CHANGELOG.md for what changed before bumping, and land the package.json/package-lock.json diff through your normal PR process, the same as any other dependency update — don't change the pin to ^ just to make updates automatic; a shared skills/constitution/ hooks package changing the rules every agent follows deserves a deliberate, reviewed bump.

Files scaffolded by init (rules.md, app-blueprint.md, SKILL_INDEX.md, workflows/*.md, tasks/lessons.md) are yours to evolve — init will never overwrite them. If a template upstream changes in a way you want to pull in, diff it manually against node_modules/@abblor/agent-os and merge by hand.

Platform requirements

agent-os link relies on real filesystem symlinks (130+ of them across skills, constitution, and hooks). This works natively on Linux and macOS. Windows is not currently verified or supported: git on Windows only checks out symlinks as real symlinks when core.symlinks=true is set and the user has Developer Mode enabled (or runs as Administrator) — without both, checked-out symlinks become plain text files containing the link target path, silently breaking every skill, the constitution, and the git hooks. If your team develops on Windows, verify this explicitly before adopting this package, or use WSL.

Contributing a new skill or fixing an existing one

This package is published from the abblor/packages repo, under agent-os/. If a skill or rule you're adding is genuinely useful beyond one project, propose it here instead of keeping it local — see skills/writing-skills/SKILL.md for authoring guidance.

Run npm test from agent-os/ before opening a PR — it packs the real tarball, installs it into a scratch directory, and exercises agent-os link/agent-os init end-to-end (idempotency, symlink-collision handling, placeholder substitution, never-overwrite behavior).