This document covers repository-internal structure, sync workflows, and validation for maintainers.
.agents/rules/is the shared rulebook..agents/skills/is the canonical shared skill library..agents/commands/is the canonical shared command library..agents/mcp.jsonis the shared MCP configuration..agents/hooks/is the canonical shared hook location (including RTK rewrite hook)..agents/bin/contains ignored local tool shims created bysetup-symlinks.sh.docs/openspec/is the OpenSpec artifact root for this tooling repo, exposed through the rootopenspecsymlink for CLI compatibility..cursor/skills-cursor/contains Cursor-only skills (Canvas, SDK, meta-skills). Inventory:.agents/docs/cursor-skills.md. Not part of skill-factory sync orvalidate-skill-library.sh.~/.cursor/skillspoints at.agents/skills/; it is not a separate tracked tree under.cursor/skills/.
.agents/rules/base.md is the compact home-level rulebook shared across repositories. Its universal behavior is organized around four operating principles: Think Before Acting, Simplest Surgical Change, Goal-Driven Verification, and Checkpoint and Escalate.
.agents/rules/repository.md is the bootstrap for this checkout: it owns the
project description, canonical validation commands, and skill-library
governance. Root AGENTS.md, CLAUDE.md, and GEMINI.md shims point to it.
The universal rulebook owns contextual-rule triggers so repository shims do not
repeat them.
Repo-type details belong in contextual rule files such as .agents/rules/python-project.md and .agents/rules/makefile-project.md. Task-specific workflows belong in skills. Do not add generic best-practice prose to base.md unless it routes concrete behavior that agents cannot reliably infer from the codebase or user request.
Cursor consumes the home-level and repository AGENTS.md hierarchy directly.
Do not add an always-applied Cursor wrapper that includes base.md or
repository.md again. The only repository-wide Cursor rule is
.cursor/rules/cursor-config-management.mdc, which documents this checkout's
configuration topology.
The skill library is self-contained:
- Native skills are authored directly in
.agents/skills/. - Imported skill-factory skills are copied into
.agents/skills/and tracked in git. - Matt Pocock skills are installed into
.agents/skills/and tracked in git with provenance inskills-lock.json. - Product-management skills are tracked in
.agents/skills/with provenance inskills-lock.json. - Skill-factory provenance is tracked in
.agents/upstreams/skill-factory/components.lock.json. - ECC upstream components are tracked in
.agents/upstreams/ecc/components.lock.json.
Shared skill governance lives in:
.agents/docs/skill-factory-skills.md.agents/skills/skill-foundry/agents/catalog.yaml.agents/skills/skill-foundry/agents/catalog-engineering.yaml.agents/skills/skill-foundry/agents/catalog-product-management.yaml
Use the skill catalog supplied by the active client for ordinary task routing.
The full index and catalogs above are maintenance inventories; they are not a
required context preamble before loading one matching skill. When a client has
no catalog, search only the relevant section of
.agents/docs/skill-domain-routing.md.
Cursor-only skills are inventoried separately:
.agents/docs/cursor-skills.md- validated by
./validate-cursor-skills.sh(frontmatter + index only; no skill-foundry catalogs)
./setup-symlinks.sh setup
make install-hooks
make checkmake check is the canonical local healthcheck and runs:
make testmake lint-shellmake validate-skillsmake validate-cursor-skillsmake validate-openspecmake validate-symlinksmake check-tracked-ignored
Recommended direct checks when diagnosing a specific failure:
make lint-shell
make test
./tests/validate-skill-library-test.sh
./validate-skill-library.sh
./validate-cursor-skills.sh
OPENSPEC_TELEMETRY=0 openspec validate --allcheck-tracked-ignored is report-only. It surfaces tracked files that match .gitignore so maintainers can decide whether a path is intentional or should be removed from version control.
The TypeScript CLI under src/thoughts/ is not part of mandatory make check until dependency installation is reproducible for this repository.
The Makefile prepends ~/.agents/bin, ~/.bun/bin, /opt/homebrew/bin, and /usr/local/bin to PATH so checks can find managed tools from non-login shells.
The tracked pre-commit template lives at hooks/pre-commit and delegates to make check.
Install it with:
make install-hooksThe install target uses git rev-parse --git-path hooks/pre-commit, so it works from linked worktrees as well as the main checkout.
Use the local skill-factory checkout to refresh imported skills:
SKILL_FACTORY=/path/to/skill-factory ./pull-and-sync-skills.shWhat this does:
- pulls the upstream repository
- copies upstream skill directories into
.agents/skills/ - preserves native repo-owned skills and other external skill packs
- refreshes
.agents/upstreams/skill-factory/components.lock.json
Preview only:
SKILL_FACTORY=/path/to/skill-factory ./sync-skill-factory.sh --dry-runsetup-symlinks.sh manages these local links:
~/.cursor/commands-> repo.cursor/commands-> repo.agents/commands~/.cursor/skills-> repo.agents/skills~/.cursor/skills-cursor-> repo.cursor/skills-cursor~/.cursor/.agents-> repo.agents~/.cursor/mcp.json-> repo.agents/mcp.json~/.cursor/cli-config.json-> repo.cursor/cli-config.json~/.codex/skills/skills-> repo.agents/skills~/.codex/rules/default.rules-> repo.agents/rules/codex-default.rules~/.codex/AGENTS.md-> repo.agents/rules/base.md~/.codex/hooks/rtk-rewrite.sh-> repo.agents/hooks/rtk-rewrite.sh~/.codex/hooks.jsonis seeded fromtemplates/codex/hooks.json~/.claude/commands-> repo.agents/commands~/.claude/skills-> repo.agents/skills~/.claude/hooks-> repo.claude/hooks~/.claude/hooks/rtk-rewrite.sh-> repo.claude/hooks/rtk-rewrite.sh-> repo.agents/hooks/rtk-rewrite.sh~/.gemini/antigravity/mcp_config.json-> repo.agents/mcp.json~/.gemini/GEMINI.md-> repo.agents/rules/base.md~/.agents-> repo.agents~/.agents/bin/rtk->/opt/homebrew/bin/rtkwhen Homebrew RTK is present~/.agents/bin/openspec->/opt/homebrew/bin/openspecor~/.bun/bin/openspecwhen OpenSpec is present
Mutable local config such as ~/.codex/config.toml, ~/.codex/hooks.json, and ~/.claude/settings.json is seeded from templates/ and intentionally not symlinked back into the repo.
thoughts/shared/research/stores shared research artifacts.thoughts/shared/plans/stores implementation plans.src/thoughts/contains the CLI used to manage thethoughts/tree.
- The root shims
AGENTS.md,CLAUDE.md, andGEMINI.mdpoint to.agents/rules/repository.md; home-level instruction files point to.agents/rules/base.md. - The validator only passes when filesystem inventory, catalogs, the skills index, and domain routing entries are in sync.
- Adding, removing, renaming, or moving a skill requires the same-change updates to
.agents/docs/skill-factory-skills.md, the relevant skill-foundry governance catalog, and a bullet in.agents/docs/skill-domain-routing.md. UpdateREADME.md,PROJECT_STATUS.md, and provenance lock files when user-facing inventory, status, or source ownership changes. ./pull-and-sync-skills.shruns./validate-skill-library.shafter every sync so missing index, catalog, or routing updates fail immediately.- If a skill moves from skill-factory to another source, remove it from
.agents/upstreams/skill-factory/components.lock.json; otherwise the skill-factory sync will refresh and overwrite it.