Defame1297
adaa978d20
Why: the always-on governance.md told agents to read docs/ai-constitution.md when a decision is not covered, a path that exists only in this repo, so the fallback failed in every other project. (Simplification audit finding 27, second defect.) Implementation Notes: - Move docs/ai-constitution.md to core/ai-constitution.md; the existing core deploy step now ships it to ~/.claude/core/. - governance.md line 4 and line 73 name ~/.claude/core/ai-constitution.md; the HUMANS.md and CONTROLS.md pointers now say they live in the holocron repo. - Repoint path-qualified citations in AGENTS.md, architecture.md, skill-implementation-workflow.md and CONTROLS.md. The vendored write-skill example and the audit's historical notes are left as records. - The docs/wiki gitlink is not bumped here; the wiki commit awaits push. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
52 lines
5.4 KiB
Markdown
52 lines
5.4 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). On `main`, commit or discard it deliberately. On a feature branch, discard it (`git checkout -- apm.lock.yaml`, then `apm install`). This keeps unrelated lock churn out of the branch diff and keeps `apm pack --check-clean` consistent with the committed lock. The session then runs the older `main` that the lock records, which is accepted on a branch, and the next session start refreshes again.
|
|
- **A `.apm/` edit is not live until it is on the remote's `main`.** The six dependencies resolve from the holocron remote, unpinned against the default branch, so pushing a feature branch does not deploy it (ADR-0019). `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
|
|
- `core/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`
|