fimoklei/pm-ai-playbook/intent-layer

Intent Layer

Context infrastructure that helps agents find local rules, understand ownership boundaries, verify changes, and notice when context may be stale.

Root Context Strategy

Default: use AGENTS.md as the canonical cross-agent source. Use CLAUDE.md as a thin Claude Code adapter when Claude Code is used.

Supported modes:

Adapter example:

@AGENTS.md
 
## Claude Code Specific Instructions
 
-Prefer editing existing files over creating new abstractions.
-Use plan mode for large refactors.
-Run local verification commands before final response.

Child AGENTS.md files in subdirectories are encouraged for complex subsystems. Root adapters should point to canonical context instead of duplicating it.

Required Root Intent Layer

Add this to the canonical context file at project root: AGENTS.md by default, or CLAUDE.md in CLAUDE-only mode. In adapter mode, add it to AGENTS.md; CLAUDE.md imports it.

## Intent Layer
 
**Before modifying code in a subdirectory, read its AGENTS.md first** to understand local patterns and invariants.
 
-**[Area 1]**: `path/to/AGENTS.md` - Brief description
-**[Area 2]**: `path/to/AGENTS.md` - Brief description
 
### Global Invariants
 
-[Invariant that applies across all areas]
-[Another global invariant]

This navigation contract is mandatory when child context nodes exist. Extend it with the project's real boundaries and global invariants; do not leave placeholder areas in finalized context.

Workflow

1. Detect state
   scripts/detect_state.sh /path/to/project
   -> Returns: none | partial | complete
 
2. Route
   none/partial -> Initial setup (steps 3-5)
   complete     -> Maintenance (step 6)
 
3. Measure [gate - show table first]
   scripts/analyze_structure.sh /path/to/project
   scripts/estimate_tokens.sh /path/to/each/source/dir
   scripts/check_context_staleness.sh /path/to/project
 
4. Decide
   No root file        -> Ask which supported mode to use
   Existing root files -> Preserve intent; add adapter/import only if useful
   Child nodes needed  -> Add local AGENTS.md files with verification commands
 
5. Execute
   Add the Required Root Intent Layer to the canonical root context file
   Use references/templates.md for structure
   Use references/node-examples.md for real-world patterns
   Validate: canonical source is clear, READ-FIRST directive exists, every node has Verification, <4k tokens per node
 
6. Maintenance mode (when state=complete)
   Ask user:
   a) Audit nodes     -> Use references/capture-protocol.md for SME questions
   b) Find candidates -> Re-measure tokens, suggest new nodes
   c) Staleness check -> Run scripts/check_context_staleness.sh
   d) Both/all

When to Create Child Nodes

Do NOT create for: every directory, simple utilities, test folders (unless complex).

Staleness Risk Levels

scripts/check_context_staleness.sh uses git history as a review trigger, not as proof that context is wrong.

Capture Questions

When documenting existing code, ask:

1. What does this area own? What's out of scope?
2. What invariants must never be violated?
3. What repeatedly confuses new engineers?
4. What patterns should always be followed?

Resources

Scripts:

• scripts/detect_state.sh - Check Intent Layer state (none/partial/complete)
• scripts/analyze_structure.sh - Find semantic boundaries
• scripts/estimate_tokens.sh - Measure directory complexity
• scripts/check_context_staleness.sh - Flag context nodes with code movement since their last update

References:

• references/templates.md - Root and child node templates
• references/node-examples.md - Real-world examples
• references/capture-protocol.md - SME interview protocol