Files

Defame1297 4d336bbf35 docs: stop the preloaded instruction set asserting machine state

Why: four defects in the files every session pays for, all introduced or left
behind by the trim.

AGENTS.md told agents the `<plugin>:` form still resolves "because user-scope
native installs were left enabled on purpose", and that a working namespaced
call "is not something to fix". That premise is false on this machine:
installed_plugins.json is empty, no enabledPlugins key exists in ~/.claude.json,
and ~/.apm/marketplaces.json is empty. ADR-0018 already reversed itself once on
this exact claim (Correction 2026-08-14) using that same enablement as its
evidence, so flipping the assertion again would be the third revision in three.
Both files now assert nothing about install state at all, which removes the
flip-flop surface instead of re-aiming it.

The other three are guard-rails whose instruction survived the trim while the
caveat that made it safe did not:
- The run-tests.sh line omitted --strict, so it named the one invocation that
  reports SKIPPED rather than failed when a dependency is missing. gates.md
  records this gate going green having verified 15 of 17 suites on a vale-less
  PATH. .pre-commit-config.yaml:70 already uses --strict for that reason.
- The .claude/settings.json prohibition lost its ADR-0019 exception, so an agent
  applying it literally would strip apm's own merged SessionStart entry and
  create the drift the rule exists to prevent.
- LESSONS.md still routed graduated rules to CONTEXT.md's Principles section,
  which this branch deleted.

Implementation notes: the six terms the trim dropped while AGENTS.md still
claimed CONTEXT.md glosses everything -- authoring root, content mirror, apm
package, output profile, near-miss, vacuous green -- are restored as one-line
entries per CONTEXT-FORMAT.md, sourced from architecture.md, gates.md and
skill-audit's description-quality.md rather than reworded. ADR-0018 gets a third
dated note recording the observation and the fact that the state has now been
described two ways, and its stale user-scope inventory is replaced by a pointer
to it; the decision it records is untouched. LESSONS.md:3 carried the identical
stale claim as :5 and is fixed with it.

Impact: preloaded context is now free of assertions about machine state.

Refs: #105

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w

2026-08-17 12:28:30 +00:00

7.0 KiB

Raw Blame History

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/ — six installable plugin units, each an apm package (apm.yml + .apm/). Root apm.yml declares all six as dependencies.apm; apm install deploys them into .claude/skills/ and .claude/agents/, both gitignored install output.
providers/claude-code/ — Claude Code adapter, deployed to ~/.claude/ via scripts/install.sh.

Edit `.apm/`, never the flat mirror

plugins/<name>/.apm/ is the only hand-edited source for plugin content. The flat plugins/<name>/{skills,agents,commands,instructions,extensions}/ directories, the merged plugins/<name>/hooks/hooks.json, and both plugin.json manifests are generated — nothing marks them as generated, so check the path before you edit. An edit to the mirror is discarded by the next sync and reported as drift by the check-plugin-content-sync pre-push hook.

Not everything in a plugin root is generated. README.md, docs/, bin/, sources.md, .mcp.json and per-plugin extras are hand-authored there with no .apm/ source — edit those in place. The rule is per-path, not per-directory. But a file placed inside a mirrored directory is deleted on the next sync (sync_dir runs rm -rf before every copy), so plugin-root documentation goes in docs/, never in hooks/ or skills/.

Full model: 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 runs apm outdated at startup and apm update --yes when something is behind, which rewrites the lock. 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.
The ADR-0020 skill gates ship hot, with no baseline. 26 of 39 descriptions and 9 of 39 bodies exceed their FAIL tier, and the Kyberforge.CompositionNote Vale rule fires 10 errors across gitea-issues, gitea-labels-milestones, gitea-prs and gitea-workflow. Editing any of those skills for any reason means retrofitting it to the contract first — a one-line fix cannot be committed until the skill complies. Deliberate; tracked as Gitea issue #99. skill-size-check will not warn you about the Vale half, so check both: pre-commit run --all-files.
Run bash tests/run-tests.sh --strict before considering any change done. Keep the flag: without it a suite whose dependency is missing exits 77 and is counted SKIPPED rather than failed, so the run goes green having verified less than it claims.
Before pushing, run the whole gate locally: pre-commit run --hook-stage pre-push --all-files. Pushing runs 14 repo-defined hooks, not just the test suite.
Pushing without a network needs SKIP=apm-marketplace-check,apm-pack-check-clean git push — those two resolve a remote marketplace entry via git ls-remote. Skip only those two; the rest are real local checks, and adding one to SKIP disarms it silently.
Author commits with git-commits — it validates Conventional Commits, which commit-msg enforces.
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 language, and the terms in it are used unglossed everywhere else.

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

7.0 KiB Raw Blame History