project-context-installer — scaffold a project-local context graph
Self-validate after edits. Any change to this skill's files (SKILL.md, scripts/, references/, templates/, assets/) must be followed by ./scripts/validate.sh from the skill directory. Hard findings -> create-skill Optimize lane.
Install a repo-local context graph that mines ordered sessions into validated durable decisions and exposes them through a local project-context CLI. This skill is for setup and wiring, not for mining live decisions by hand.
Operating contract
| Field |
Decision |
| Primary archetype |
deterministic script workflow |
| Secondary archetypes |
reference workflow |
| Operator trigger |
"set up project context graph", "install project-context", "scaffold durable decision graph", "wire session-mining context graph" |
| Output |
Installed tools/project-context CLI, repo wrapper script, pinned miner agent, local docs, and repo routing updates |
| Success evidence |
installer report, repo files created, local validation commands pass |
| Deterministic surface |
scripts/install.py, generated local CLI, generated tests, scripts/validate.sh |
| Judgment surface |
deciding whether repo docs/AGENTS need additional routing beyond the default install |
| Context loading |
load this body, then references/install.md; inspect local repo AGENTS.md and docs only if present |
Main flow
Preflight
- Confirm the target repo path exists.
- If the repo has a local
AGENTS.md, retrieve the agents-md quality gate before editing it.
- If the repo has
docs/, inspect current reference/workflow surfaces before adding new ones.
- Keep the install project-local. Do not move repo-specific graph semantics into global
AGENTS.md.
Do
Run the installer:
python3 ~/.codex/skills/project-context-installer/scripts/install.py --target /abs/path/to/repo
The installer:
- writes
tools/project-context/ with a deterministic Python CLI
- writes
script/project_context.sh as the stable repo entrypoint
- updates repo docs and local
AGENTS.md with marker-safe inserts when those files exist
- writes tests and validation guidance
Closeout
- Run the generated validation commands in the target repo.
- If local
AGENTS.md changed, run workflow lint from the target repo.
- Report created files, commands run, and any gaps.
Friction introspection
At closeout, classify friction before changing this skill:
| Friction source |
Action |
| Missing installer behavior, patch rule, or validation wiring |
Update this skill |
| Generated project-context code bug |
Fix the generated scaffold and reinstall or patch target |
| Source coverage or exclusion state is not durable |
Add source inventory, watermark, and persisted resolution behavior to the generated scaffold |
| Repeated source-resolution operations are slow |
Add a batch command or cached deterministic path to the generated scaffold |
| Repo-specific docs/structure mismatch |
Fix the target repo docs or add a bounded installer branch if reusable |
| Environment dependency issue |
Improve installer diagnostics only if reusable |
| One-off local preference |
Do not widen the skill unless it becomes repeatable |
Hard rules
- Keep
workflow as control-plane routing; install repo-local graph semantics into the target repo.
- Never let subagent-mined context become trusted without validation and promotion boundaries.
- Do not bloat local
AGENTS.md; deep graph behavior belongs in repo docs and generated local tooling.
- Treat raw source-session inventory as part of graph readiness; unresolved source gaps block trust until imported, summarized, or persistently resolved.
- Prefer marker-safe inserts over broad rewrites when patching repo docs.
Cross-references
- references/install.md - installer behavior, generated surface, and validation contract
- scripts/install.py - deterministic installer
- scripts/validate.sh - skill self-validation wrapper
Why this skill exists
Without a reusable installer, every project-local context graph becomes a bespoke chat-only pattern with inconsistent trust boundaries, file placement, and validation. This skill creates one repeatable repo-local shape: ordered session mining, validator-gated promotion, and compact retrieval surfaces that future agents can actually depend on.
1---2name: project-context-installer3description: Install a project-local context graph into a repo. Use when the operator asks to set up, scaffold, install, or wire a project context graph, durable decision graph, session-mining memory graph, or `project-context` CLI. This skill creates a deterministic local Python CLI, root wrapper script, docs/workflow wiring, and validation hooks inside the target project while keeping global doctrine in `~/.codex` and repo-specific behavior in the repo.4---56# project-context-installer — scaffold a project-local context graph78> **Self-validate after edits.** Any change to this skill's files (SKILL.md, scripts/, references/, templates/, assets/) must be followed by `./scripts/validate.sh` from the skill directory. Hard findings -> create-skill Optimize lane.910Install a repo-local context graph that mines ordered sessions into validated durable decisions and exposes them through a local `project-context` CLI. This skill is for setup and wiring, not for mining live decisions by hand.1112## Operating contract1314| Field | Decision |15|---|---|16| Primary archetype | deterministic script workflow |17| Secondary archetypes | reference workflow |18| Operator trigger | "set up project context graph", "install project-context", "scaffold durable decision graph", "wire session-mining context graph" |19| Output | Installed `tools/project-context` CLI, repo wrapper script, pinned miner agent, local docs, and repo routing updates |20| Success evidence | installer report, repo files created, local validation commands pass |21| Deterministic surface | `scripts/install.py`, generated local CLI, generated tests, `scripts/validate.sh` |22| Judgment surface | deciding whether repo docs/AGENTS need additional routing beyond the default install |23| Context loading | load this body, then `references/install.md`; inspect local repo `AGENTS.md` and docs only if present |2425## Main flow2627### Preflight28291. Confirm the target repo path exists.302. If the repo has a local `AGENTS.md`, retrieve the `agents-md` quality gate before editing it.313. If the repo has `docs/`, inspect current reference/workflow surfaces before adding new ones.324. Keep the install project-local. Do not move repo-specific graph semantics into global `AGENTS.md`.3334### Do3536Run the installer:3738```bash39python3 ~/.codex/skills/project-context-installer/scripts/install.py --target /abs/path/to/repo40```4142The installer:43- writes `tools/project-context/` with a deterministic Python CLI44- writes `script/project_context.sh` as the stable repo entrypoint45- updates repo docs and local `AGENTS.md` with marker-safe inserts when those files exist46- writes tests and validation guidance4748### Closeout49501. Run the generated validation commands in the target repo.512. If local `AGENTS.md` changed, run `workflow lint` from the target repo.523. Report created files, commands run, and any gaps.5354#### Friction introspection5556At closeout, classify friction before changing this skill:5758| Friction source | Action |59|---|---|60| Missing installer behavior, patch rule, or validation wiring | Update this skill |61| Generated project-context code bug | Fix the generated scaffold and reinstall or patch target |62| Source coverage or exclusion state is not durable | Add source inventory, watermark, and persisted resolution behavior to the generated scaffold |63| Repeated source-resolution operations are slow | Add a batch command or cached deterministic path to the generated scaffold |64| Repo-specific docs/structure mismatch | Fix the target repo docs or add a bounded installer branch if reusable |65| Environment dependency issue | Improve installer diagnostics only if reusable |66| One-off local preference | Do not widen the skill unless it becomes repeatable |6768## Hard rules69701. Keep `workflow` as control-plane routing; install repo-local graph semantics into the target repo.712. Never let subagent-mined context become trusted without validation and promotion boundaries.723. Do not bloat local `AGENTS.md`; deep graph behavior belongs in repo docs and generated local tooling.734. Treat raw source-session inventory as part of graph readiness; unresolved source gaps block trust until imported, summarized, or persistently resolved.745. Prefer marker-safe inserts over broad rewrites when patching repo docs.7576## Cross-references7778- [references/install.md](references/install.md) - installer behavior, generated surface, and validation contract79- [scripts/install.py](scripts/install.py) - deterministic installer80- [scripts/validate.sh](scripts/validate.sh) - skill self-validation wrapper8182## Why this skill exists8384Without a reusable installer, every project-local context graph becomes a bespoke chat-only pattern with inconsistent trust boundaries, file placement, and validation. This skill creates one repeatable repo-local shape: ordered session mining, validator-gated promotion, and compact retrieval surfaces that future agents can actually depend on.
ingpoc