context-manifest

name

context-manifest

description

Govern project and agent-workspace context using a persistent MANIFEST.md file. Use when initializing, auditing, updating, or consuming context for a repo, project folder, or agent workspace; especially when many files exist, stale drafts or archives can pollute context, or sub-agents need minimal scoped context. Prefer project-level MANIFEST.md when both project and agent-workspace manifests exist. Aggressively maintain MANIFEST.md as the source of truth for context loading.

Context Manifest

Use MANIFEST.md as the persistent context control plane for projects and agent workspaces.

Core intent

Reduce context pollution, stale-file confusion, token waste, and sub-agent overexposure by declaring what is authoritative, what is domain-scoped, and what must stay out of context.

Placement priority

1. Prefer a project/repo root MANIFEST.md.
2. Also allow an agent-workspace root MANIFEST.md.
3. If both exist, prefer the project manifest first, then use the workspace manifest only for workspace-local behavior.

Required sections

Create and maintain these sections:

Canonical

List the current source-of-truth files that must be read first.

Domain Map

Map folders or file groups to specific domains. Load only when the task touches that domain.

Archive

List superseded drafts, historical material, or deprecated plans. Do not load unless explicitly requested.

Ignore

List logs, caches, generated artifacts, screenshots, temporary exports, and other noise. Never load into context.

Sensitive

List files or paths that may exist but must not be passed into agent or sub-agent context without explicit user approval.

Operating Rules

Record project-specific rules such as preferred output paths, review flow, approval gates, recommended skills, model defaults, and tool restrictions.

Loading rules

1. Read MANIFEST.md before broad file exploration.
2. Load Canonical first.
3. Load Domain Map entries only when directly relevant.
4. Never load Archive or Ignore by default.
5. Treat Sensitive as blocked unless the user explicitly authorizes access.
6. When spawning sub-agents, pass only the minimum context required for the relevant domain.

Instruction layering

Use this precedence model for non-safety behavior:

1. System and platform safety boundaries
2. Personal layer (SOUL.md, USER.md, stable MEMORY.md rules)
3. Project layer (MANIFEST.md)
4. Current task instructions

Apply these conflict rules:

• Never let lower layers override safety boundaries.
• Let current task instructions override project defaults for this run.
• Let project rules override personal defaults when the project needs a different workflow or output shape.
• Keep personal tone and collaboration style when they do not conflict with project or task constraints.
• If ownership is unclear, mark VERIFY instead of inventing precedence.

Scoped Context Loading

Use MANIFEST.md to build the smallest context bundle that can still complete the task well.

Routing flow

1. Classify the task into one or more domains.
2. Load Canonical files first.
3. Load only the Domain Map entries needed for those domains.
4. Exclude Archive and Ignore.
5. Block Sensitive unless explicitly approved.
6. Package only the relevant context for the receiving agent or sub-agent.

Hard rules

• Prefer minimum sufficient context over maximum possible context.
• Do not widen scope just because extra files might be useful.
• If a task spans multiple domains, include only the relevant slices from each domain.
• Give sub-agents scoped context bundles, not the full project background.
• If the domain match is uncertain, mark VERIFY or ask instead of overloading context.

Scoped task package

When delegating, include only:

• task goal
• success criteria
• relevant constraints
• required canonical files or excerpts
• required domain files or excerpts
• output requirements
• uncertainty handling rules

Favor auditable, replayable task packages so later failures can be traced back to the context bundle that was actually used.

Transactional Execution

Use a plan-approve-execute pattern for actions with side effects.

Risk levels

Level 0 — Read-only

Execute directly for analysis, reading, search, summarization, and other no-side-effect work.

Level 1 — Low-risk reversible changes

Use a brief plan and proceed when the user has already asked directly or the change is clearly recoverable.

Level 2 — Medium/high-risk actions

Show a plan and wait for explicit approval before execution.

Examples:

• batch rename or move
• config edits
• external sends
• account linking or login
• scheduled task changes
• multi-file edits
• sub-agent tasks that will modify files

Level 3 — High-impact or uncertain actions

Show a detailed plan, risks, validation path, and rollback path, then wait for explicit approval.

Examples:

• gateway behavior changes
• broad workspace restructures
• destructive operations
• privileged commands
• sensitive-data access
• public posting or bulk outbound actions

Plan requirements

Before execution, state:

1. what will change
2. what will not change
3. which files, folders, systems, or channels are affected
4. how success will be verified
5. how rollback will work

Approval rules

• Reuse the user's established approval habit when available.
• Treat 1 as approval when the active collaboration pattern defines it that way.
• Do not treat silence or ambiguity as approval.

Execution completion

After execution, report:

1. completed actions
2. verification result
3. rollback path if follow-up issues appear

Uncertainty Protocol

Expose uncertainty instead of hiding it.

Core rules

1. Mark uncertain classifications, ownership, dates, mappings, or precedence with VERIFY.
2. Route ambiguous items to needs-review instead of forcing a final placement.
3. Surface source conflicts explicitly; do not silently choose one side.
4. Do not allow low-confidence judgments to trigger destructive or hard-to-reverse actions.
5. Attach the smallest useful verification path whenever possible.

When to use VERIFY

Use VERIFY for cases such as:

• unclear canonical status
• ambiguous domain ownership
• unclear recency or replacement status
• conflicting file versions
• unclear instruction precedence
• incomplete external evidence

Review routing

If an item cannot be safely resolved automatically:

• place it in needs-review, or
• list it in a dedicated review section or change log

Prefer visible review queues over silent guessing.

Confidence gating

• High confidence: proceed normally.
• Medium confidence: proceed only with visible VERIFY markers or review notes.
• Low confidence: stop, ask, or route to review before any high-impact action.

Maintenance rules

Aggressively maintain the manifest as files evolve.

1. Add newly-important source-of-truth files when they appear.
2. Mark stale or missing paths promptly.
3. Preserve user-authored notes and intent; do not overwrite silently.
4. If classification is unclear, mark the entry VERIFY instead of guessing.
5. Favor concise, high-signal entries over exhaustive inventories.

Suggested operating pattern

Initialize

Scan the folder, identify high-signal files, then generate the first MANIFEST.md.

Refresh

When structure changes, update impacted sections instead of rewriting the whole file.

Consume

Use the manifest to decide what to read, what to skip, and what to keep away from sub-agents.

Safety

• Do not treat every file in a folder as equally trustworthy.
• Do not expose Sensitive paths to sub-agents without explicit approval.
• Do not silently pull archival content into current decision-making.
• Do not treat external evidence as canonical project truth until it has been verified.
• Prefer narrower context over larger context when quality is uncertain.

Minimal template

# MANIFEST.md

## Canonical
- PRD.md — current product requirements
- ARCHITECTURE.md — active system design

## Domain Map
- /research — competitor and reference analysis
- /scripts — automation and helpers
- /docs — working documentation

## Archive
- /archive — superseded drafts and retired plans

## Ignore
- /logs
- /dist
- /tmp

## Sensitive
- /secrets
- finance/private

## Operating Rules
- Default output path: /deliverables
- Ask before destructive changes
- Prefer minimal context for sub-agents

References

Read these references as needed:

• references/manifest-examples.md for stronger MANIFEST.md examples, dual-manifest conflict handling, and review patterns
• references/scoped-task-package.md for a reusable sub-agent context bundle template
• references/task-domain-routing.md for task-to-domain routing rules before loading context
• references/operating-rules-fields.md for recommended Operating Rules fields and what belongs there external material should stay separated