Defame1297
807caf22ee
Why: the docs said to discard a refreshed apm.lock.yaml on a feature branch because the refresh records main's commit, but the branch's own lock records a (older) main commit too, and the SessionStart notice gave the same "commit or discard" advice on every branch. Implementation Notes: - check-apm-current.sh picks fixed advice by branch: commit or discard deliberately on the default branch (origin/HEAD, else main), discard and reinstall on a feature branch; the branch name is never interpolated. - README, AGENTS.md and ADR-0019 give the real reasons (no lock churn in the branch diff, deployed tree matches the committed lock), the cost (the session runs the older main) and that the next session start refreshes again. - ADR-0019's check-clean and stale-server claims restated to match apm's source. ADR: 0019 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
|
|
- `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`
|