docs: separate stable agent contract from living project context - #12
Merged
Merged
Conversation
Add a private-fork operating contract at the top of AGENTS.md that captures durable mission, long-term priorities, engineering method, CI policy, and skill-routing expectations while preserving the upstream llama.cpp agent instructions below it. Treat repository-local skills as first-class workflows: keep Ponytail as the default implementation discipline, route ambiguous non-trivial work through ask-matt, and explicitly use focused debugging, research, design, TDD, planning, merge-conflict, correctness-review, and complexity-review skills where appropriate. Move changing information out of the root contract into living docs for current priorities, technical/runtime context, and optimization history. This keeps AGENTS.md stable while allowing hardware, models, benchmarks, active experiments, source SHAs, and near-term priorities to evolve without rewriting the project's durable instructions.
Apply the setup-matt-pocock-skills repository conventions to the private fork. Reshape the existing skill guidance into the expected Agent skills block and record the project's GitHub issue tracker, default triage-label vocabulary, and single-context domain-doc layout under docs/agents. Preserve the stable AGENTS.md versus living docs/agents split: AGENTS.md points at the configuration and durable workflow, while domain vocabulary, ADRs, and changing operational context remain in their dedicated files. Adapt the upstream setup templates to the private-fork boundary so issue automation conventions do not override llama.cpp's upstream contribution rules.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reworks the repository agent guidance around a stable-root / living-docs model, then applies the
setup-matt-pocock-skillsrepository workflow to that structure.AGENTS.md now carries durable policy
The private-fork section captures:
The upstream llama.cpp contributor instructions remain intact below it.
Matt Pocock setup workflow applied
Adds the configuration files expected by the engineering skills:
docs/agents/issue-tracker.md- GitHub Issues in the private forkdocs/agents/triage-labels.md- default five-role triage vocabularydocs/agents/domain.md- single-context domain-doc layout and consumer rulesThe
## Agent skillsblock inAGENTS.mdnow points at those files using the setup skill's intended structure.The setup is adapted to the private-fork boundary: issue automation conventions apply to
bryanwieg/llama.cpp, while upstreamggml-org/llama.cppcontribution restrictions remain unchanged.Skills are first-class
The contract tells agents to invoke the installed workflows rather than approximate them from memory:
Living docs
Adds:
docs/agents/current-state.mddocs/agents/technical-context.mddocs/agents/optimization-history.mdThe domain configuration now explicitly defines the separation:
AGENTS.md= stable operating contractCONTEXT.md= shared domain language, created lazily when usefuldocs/adr/= durable architectural decisionsdocs/agents/= changing operational/project contextThis should let the root contract stay stable while hardware, models, benchmarks, experiments, tooling state, and recent priorities evolve independently.