Agent Project Context

Agent Project Context is the strategic context layer for coding agents in the Agent Toolkit portfolio.

It exists for the information that strong agents still miss after reading code:

• what the product is trying to achieve
• which users and workflows matter most
• which architectural boundaries are product-critical
• which constraints and non-goals must not be violated
• which domain terms and entities the team uses
• which conventions, priorities, and decisions should guide execution

This repo is not trying to become a generic wiki, a chat archive, or a replacement for code search. It should become the smallest durable context surface that helps an agent understand a project faster and make better decisions.

Product thesis

Code search tells an agent how the system is implemented.

Project context should tell an agent:

• why the system exists
• who it is for
• what outcomes matter
• where the important boundaries are
• what is intentionally out of scope
• which decisions are still authoritative

That is the layer an agent needs before it plans product-sensitive work.

Current state

The repo has a structured project-context model (APC-101, done), an active-slice resolver (APC-102, done), and full toolkit integration (APC-103, done) with 19 MCP tools.

What is built today:

• flat-file storage in .project-context/ with 12 JSON files
• a TypeScript MCP server with 19 tools (8 structured context + 1 resolver + 1 memory-aware resolver + 1 coordinator-aware resolver + 1 guardian-aware export + 5 preserved + 2 legacy compat)
• Zod schemas with SectionMeta on all sections and ItemMeta on most item types (stakeholder and competitor entries use section-level metadata only)
• context sections: product thesis, goals, non-goals, user flows, boundaries, constraints, glossary/entities, conventions, stakeholders, decisions, competitive context, and roadmap
• provenance metadata (sourceRefs, memoryRefs, updatedAt, tags, status) on most items; stakeholder and competitor entries rely on section-level provenance
• resolve_project_context(...) for active-slice retrieval with composable filters
• resolve_project_context_from_memory(nodeId?, includeAncestorTags?) for memory-aware context resolution
• resolve_guardian_context(nodeIds?, tags?, includeAncestorTags?) for guardian-aware export of project-specific rules
• legacy compatibility wrappers for get_project_brief and update_brief
• local agent-memory wiring via .mcp.json
• seeded project data in .project-context/ for repo dogfooding

What is still missing from the real product:

• import/update workflows from real repo docs instead of manual JSON editing
• a meaningful demo that proves agents make better decisions with this tool

The current implementation is MCP-first. There is no real user-facing CLI yet.

Context sections

| Section | File | Schema | Tool | |---------|------|--------|------| | Product thesis | product-thesis.json | ProductThesisSchema | get_product_thesis | | Goals | goals.json | GoalsSchema | get_goals | | Non-goals | non-goals.json | NonGoalsSchema | get_non_goals | | User flows | user-flows.json | UserFlowsSchema | get_user_flows | | Boundaries | boundaries.json | BoundariesSchema | get_boundaries | | Constraints | constraints.json | ConstraintsSchema | get_constraints | | Glossary | glossary.json | GlossarySchema | get_glossary | | Conventions | conventions.json | ConventionsSchema | get_conventions | | Stakeholders | stakeholders.json | StakeholderMapSchema | get_stakeholders | | Decisions | decisions.json | DecisionLogSchema | get_decisions / log_decision | | Competitive | competitive.json | CompetitiveContextSchema | get_competitive_context | | Roadmap | roadmap.json | RoadmapStateSchema | get_roadmap_status |

Most collection items carry shared item metadata: id, tags, sourceRefs, memoryRefs, updatedAt, and status (active / deprecated / draft). Stakeholder and competitor entries carry only domain-specific fields and rely on section-level metadata for provenance.

Every section wrapper carries SectionMeta: updatedAt, sourceRefs, tags, memoryRefs.

Provenance: sourceRefs vs memoryRefs

Context items carry two kinds of provenance links:

• sourceRefs — pointers to docs, files, ADRs, or URLs. These are the human-readable evidence trail: ["README.md", "ADR-001"].
• memoryRefs — explicit links to agent-memory nodes. These connect strategic context to execution history:

  { "nodeId": "FEAT-001", "relation": "implemented-by", "note": "APC-101" }

  Relations: derived-from, decided-in, implemented-by, tracked-by.

sourceRefs says where a context item is documented. memoryRefs says which agent work produced or tracks it.

Quickstart

npm install
npm run build
npm test

Wire the repo into your MCP client by pointing at dist/server.js or by using the local .mcp.json.

If .agent-memory/ is empty on a fresh clone, bootstrap it with:

npm run bootstrap-memory

Recommended agent workflow

1. Call boot_context().
2. If memory is empty or does not resolve an active node, run npm run bootstrap-memory.
3. Read README.md, ROADMAP.md, PAIN-POINTS.md, docs/IDEAL-PROJECT-CONTEXT.md, and docs/BACKLOG.md.
4. Use Agent Project Context when the task touches product behavior, naming, user-facing flows, constraints, architecture boundaries, or roadmap prioritization.
5. Record plan, decisions, and meaningful progress in Agent Memory.
6. Finish with finalize_node(summary="...").

Docs

• ROADMAP.md - product direction and phases
• PAIN-POINTS.md - failures this module should eliminate
• docs/IDEAL-PROJECT-CONTEXT.md - north-star product shape
• docs/BACKLOG.md - next execution slices in build order

Relationship to the rest of the toolkit

Each toolkit layer has a distinct role:

• Agent Memory = continuity. It remembers what happened across sessions.
• Agent Coordinator = live state. It shows who is active and what they claim.
• Agent Project Context = strategic rules. It supplies the durable product knowledge that code search cannot recover: goals, constraints, conventions, boundaries, decisions, and non-goals.
• Agent Guardian = validation. It checks risk and quality on the change surface using generic heuristics (secrets, deps, complexity) plus project-specific rules exported from Project Context.

The integration surface:

• resolve_project_context_from_memory(...) bridges Memory → Context
• resolve_project_context_from_coordinator(...) bridges Coordinator → Context
• resolve_guardian_context(...) bridges Context → Guardian

The recommended agent boot sequence:

1. memory for continuity
2. project context for strategic understanding
3. coordinator for live situational awareness
4. guardian for validation before risky changes (informed by project context)