Defame1297
f91babcacd
Why: AGENTS.md's Structure bullet restated apm-install mechanics already owned by docs/spec/architecture.md:24 and README.md:55, and docs/VISION.md carried stack, framework and deployment choices for a product that lives in a separate repo. Implementation notes: AGENTS.md keeps two actionable one-liners plus pointers to the README layout table and architecture.md, preserving the session rule that .claude/skills/ and .claude/agents/ are install output and must not be edited. VISION.md's Phase 1 Architecture block becomes a one-line scope statement; the "Mobile/desktop (Phase 3)" line is dropped as an intra-file duplicate of the Phase 3 section. Impact: no behaviour change. README.md and docs/spec/architecture.md are untouched -- the finding's premise was inflated, and architecture.md had already been differentiated in a way it documents in the file itself. Refs: SIMPLIFICATION-AUDIT.md finding 32 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
52 lines
5.0 KiB
Markdown
52 lines
5.0 KiB
Markdown
# Working in this repo
|
|
|
|
The global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects.
|
|
|
|
This file carries only what applies to **every** session. Setup, prerequisites, and test commands are in `README.md`; the reasoning behind each enforcement gate is in `docs/spec/gates.md`.
|
|
|
|
## Structure
|
|
|
|
- `plugins/<name>/.apm/` is the only authoring source for plugin content. `.claude/skills/` and `.claude/agents/` are gitignored `apm install` output — never edit them.
|
|
- `providers/claude-code/` is the Claude Code adapter, deployed to `~/.claude/` by `scripts/install.sh`.
|
|
|
|
Repo layout table: `README.md`. Deployment mechanics and plugin boundaries: `docs/spec/architecture.md`.
|
|
|
|
## Prefer plugin skills over raw shell
|
|
|
|
This repo dogfoods its own plugins. Before shelling out, check whether a skill already owns the operation — it usually does:
|
|
|
|
- Commits, branches, history, worktrees, remotes → `git-commits`, `git-branches`, `git-history`, `git-worktrees`, `git-remotes`
|
|
- Pre-commit hook install/config/troubleshooting → `pc-run` / `pc-author`
|
|
- Issues, PRs, labels, milestones → `gitea-issues`, `gitea-prs`, `gitea-labels-milestones`; also `gitea-branches`, `gitea-files`, `gitea-releases`, or `gitea-workflow` when the domain is ambiguous
|
|
- Vale prose linting → `vale-config` / `vale-run`
|
|
- This repo's own AGENTS.md → `agentsmd-author` / `agentsmd-audit`
|
|
|
|
Use the bare, **unnamespaced** names. That is what `apm install` deploys and the only form this repo's own install produces — a project skill has no plugin to prefix (ADR-0018). Whether the `<plugin>:` form (`gitea:gitea-prs`) also resolves depends on native plugin installs at user scope, outside this repo; write the bare name either way.
|
|
|
|
Fall back to raw shell only when no skill covers it.
|
|
|
|
## Session rules
|
|
|
|
- **Do not add repo-owned keys to `.claude/settings.json`.** apm treats it as its own deployed artifact and `apm audit --ci` replays the install and diffs, so anything apm would not have written is permanent drift that fails the `apm-audit-ci` pre-push hook. A hook you want here is authored in `plugins/<name>/.apm/hooks/` and deployed by apm, never hand-written into that file. The `SessionStart` entry already in it is exactly that: kyberforge authors it in `plugins/kyberforge/.apm/hooks/hooks.json` and apm merges it in, so it is apm's own output, it is what the replay expects, and it belongs in the commit — do not strip it (ADR-0019). Machine-specific settings go in the gitignored `.claude/settings.local.json`; shared enforcement goes in `.pre-commit-config.yaml`.
|
|
- **`apm.lock.yaml` turning up modified is expected, not a bug.** kyberforge's `SessionStart` hook keeps the install current on launch and rewrites the lock in the process (ADR-0019). Commit or discard it deliberately.
|
|
- **A `.apm/` edit is not live in this session until it is pushed.** The six dependencies resolve from the holocron remote, unpinned against the default branch. `apm install` deploys from the lock; `apm update` is what re-resolves refs.
|
|
- **No pre-push hook needs the network.** Root `apm.yml`'s marketplace has no remote package entries, so every hook resolves locally.
|
|
- **This repo and Gitea are the only source of truth.** All project state, decisions, and working conventions live here. Do not use an external memory system for this project — cached state diverges from the repo and you get a split brain. Before answering any design or architecture question, check `docs/adr/` for an existing decision.
|
|
|
|
## Key documents
|
|
|
|
Read `CONTEXT.md` at the start of every session — it is this repo's domain glossary, and the terms it defines are used unglossed everywhere else. It is not exhaustive: terms it does not carry are defined at their point of use, mostly in `docs/spec/`.
|
|
|
|
Read these on demand:
|
|
|
|
- `README.md` — prerequisites, install, and test commands
|
|
- `docs/VISION.md` — the phased roadmap and where this is going; read when a decision turns on product direction
|
|
- `LESSONS.md` — patterns that went wrong once; read before repeating a class of change that has burned the repo before
|
|
- `docs/spec/gates.md` — what each pre-commit and pre-push hook enforces and why; read when a gate fails or before changing hook config
|
|
- `docs/spec/architecture.md` — directory structure, install pipeline, provider model
|
|
- `docs/adr/` — architectural decisions; read before answering design questions or proposing structural changes
|
|
- `docs/ai-constitution.md` — full governance evidence base; read when a governance decision needs justification
|
|
- `docs/research/ai-coding-factory/ai-coding-factory-principles.md` — factory design rationale; read when implementing, auditing, or reviewing skills or factory structure
|
|
- `docs/notes/factory-integration-decisions.md` — decisions from the factory integration grill; read when making skill authoring or factory design decisions
|
|
- Governance rules are always in effect — `core/instructions/governance.md` (agent rules); `docs/research/governance_principles/CONTROLS.md`
|