@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/          40 skills: core methodology (superpowers), extended
                   stack skills (web-ui, api-design, avd,
                   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@latest npm pkg set 'devDependencies.@abblor/agent-os=latest' npm update @abblor/agent-os --package-lock-only

2. **Link the shared, generic content** (skills, hooks, constitution) into
your repo's `.agents/`:
```bash
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. Package-owned paths replace stale local copies with links to the installed package. App-only skills (e.g. .agents/skills/<Project>-Domain-Expert/) and project-owned Git hooks are preserved.

Version policy: Every consumer must declare "@abblor/agent-os": "latest" in package.json. After a release, run npm update @abblor/agent-os to refresh the lockfile and install the newest published package. Do not pin an exact version or range.

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

Every consumer must use the latest dist-tag. Refresh to the latest published package and update the lockfile with:

npm update @abblor/agent-os
npx agent-os check                    # confirm every new skill is routed in your SKILL_INDEX.md

Keep "@abblor/agent-os": "latest" in the consumer manifest. A normal npm update @abblor/agent-os installs the newest published release and its postinstall automatically refreshes package-owned skills, constitution, and Git hooks. No per-project approval policy, token setup, or manual relinking is needed. The package constitution is the sole delivery-policy owner: standing authorization covers current and future feature pushes and PR merges, while direct main/master pushes remain forbidden.

npm ci intentionally installs the recorded lockfile version; latest does not override that reproducibility guarantee. Refresh and commit the lockfile when adopting a release. Installs with lifecycle scripts disabled cannot run automatic setup; use a normal scripts-enabled install, or run agent-os link as an explicit recovery command. The package does not modify dependency versions through a nested install inside postinstall.

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. App-only skill directories and project-owned symlinks are never removed. Package-owned paths are always linked to the installed npm package, replacing stale local copies. 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. Keep the manifest specifier latest, including when npm's save-exact setting would otherwise write a version. The lockfile records the concrete installed release for reproducible builds.

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).