AGENTS.ctx: CRISP Workflow Detail

Level 3 (Detail) — Project creation, verification loop, split integrity, registry updates, research markers.

Concept

CRISP projects follow a structured lifecycle from creation to completion. The workflow is defined in AGENTS.ctx/crisp/CONTEXT.md. Research Grounding Rule: Before implementing any migration, verify the real deployed state with CLI tools. Manifest YAML and research files describe intent, but the actual running state may differ — e.g., Vault paths can be directories with sub-paths instead of leaf keys. Always check reality before coding.

Project Creation

User says "create project X"
  → mkdir -p AGENTS.ctx/crisp/projects/<name>/web-research
  → Add to Project Registry table (Draft state)
  → Check Research Index in parent's web-research/INDEX.md
  → Start CRISP Verification Loop

Naming Rules

  • Root projects: semantic kebab-case (e.g., hetzner-vault-platform)
  • Subprojects: numeric prefix starting at 10, incrementing by 10 (e.g., 10-hetzner-vault-foundation)
  • Recursive: children of subprojects also use prefixes

web-research/ Folder Rule

  • Only leaf (implementation) projects have web-research/ folders
  • Intermediate parent nodes do NOT — when a project is split, research moves to children
  • Research files use descriptive names (e.g., VSO vs ESO_ Gestione Segreti Kubernetes.md)

CRISP Verification Loop

The CRISP process is now a mandatory verification cycle:

  1. Context & Questions — identify all unknowns about the current state
  2. Deep Research — for each unknown involving external systems, propose a research prompt to the user; after approval, execute research and save to web-research/
  3. Design — draft DESIGN.md, mark statements as [🔍 da verificare] or [🔍 confermato da: ...]
  4. Plan — draft PLAN.md, every task must carry a verification marker
  5. Repeat — for any unverified item, do more research. Continue until every part of the plan is confirmed
  6. Handoff — only then pass to crisp-build

PLAN.md Verification Markers

Every task in PLAN.md MUST carry one of:

  • [🔍 da verificare] — not yet confirmed by research. Must be resolved during CRISP design phase.
  • [🔍 confermato da: web-research/<file>.md] — confirmed by research artifact.

Design is NOT complete until ALL markers are [🔍 confermato da: ...].

Project Lifecycle

  1. Draft: Initial creation, no research done
  2. In Progress: Research/Design/Plan phases active with verification loop
  3. Completed: All tasks executed, project closed
  4. Deprecated: Historical record only

Review Workflow

When reviewing an existing project:

  1. Load all project files (RESEARCH.md, DESIGN.md, PLAN.md, web-research/)
  2. Identify strengths, gaps, risks, inconsistencies
  3. Identify PLAN.md items marked [🔍 da verificare] and propose research
  4. Work one point at a time, discuss and decide
  5. Re-evaluate research markers after every plan change: when DESIGN.md or PLAN.md is modified, check every changed item against existing research. If confirmed, mark [🔍 confermato da: ...]. If unverified, mark [🔍 da verificare] and propose new research.
  6. Update project files immediately after each decision
  7. Propose splitting when the plan grows too large

Split Types

Two ways to split a project:

Vertical Split (children)

Parent becomes non-implementative. Parent’s PLAN.md and web-research/ move to children. Each child inherits research relevant to its scope.

Horizontal Split (siblings)

One project divides into two same-level projects. Research files distributed between them based on new scope. Original project may be retired or become a parent.

Split Integrity (Non-Negotiable)

When splitting a project:

  1. Create all child directories FIRST
  2. Populate child web-research/, RESEARCH.md, DESIGN.md, PLAN.md
  3. Verify every detail from parent PLAN.md is carried to at least one child
  4. Verify all parent research files are present in at least one child
  5. Only then update the parent to reflect the split
  6. Only then remove/replace parent PLAN.md and parent web-research/

No information may be lost during a split, whether vertical or horizontal.

tasks.md During crisp-build

When crisp-build creates tasks.md:

  1. Read all research files referenced in PLAN.md markers
  2. Inherit markers: each task starts with the marker from its parent PLAN.md item
  3. Add new [🔍 da verificare] if granular tasks expose details research didn’t cover
  4. Research before implementing any task with [🔍 da verificare]
  5. No task may be executed until confirmed

Registry Updates

When modifying a context or project, update BOTH:

  • The context’s internal files
  • The parent registry table in AGENTS.ctx/CONTEXT.md

See Also