AGENTS.ctx: CRISP Methodology

Level 2 (Topic) — Research & Design Workbench phases, project hierarchy, build handoff.

Concept

CRISP is a structured methodology for technical project design. It enforces a clear separation between the “thinking” phase (CRISP) and the “doing” phase (crisp-build).

DEEP RESEARCH FIRST: Every CRISP project must start with a deep research phase. Ideas, designs, and plans are drafts until confirmed by research. Every assertion in DESIGN.md and PLAN.md must be traceable to a web-research/ artifact.

RESEARCH GROUNDING RULE: Research files and manifest YAML describe how things SHOULD work. Before implementing any migration or change, verify the REAL deployed state with CLI tools (kubectl, vault CLI, etc.). Never assume a Vault path is a leaf path just because an ExternalSecret references it — the actual Vault structure may differ.

The 5 Phases

C — Context & Questions

Generate targeted questions about the current codebase state. “Don’t tell me what you want to do, tell me what you don’t know.” Flag topics requiring external research.

R — Research (Objective)

Map files, data flows, dependencies, and current operational reality. Run deep research on external systems (CRDs, APIs, operators). Save findings as .md files in web-research/. Opinion-free description of “how it works today.” Output: RESEARCH.md + web-research/ artifacts.

I — Intent & Design Discussion

Human-agent alignment. Propose 2-3 approaches, choose one with trade-offs. Mark every key assertion with [🔍 da verificare] or [🔍 confermato da: ...]. Output: DESIGN.md.

S — Structure Outline

Define the skeleton: function signatures, interfaces, config keys, template insertion points. Output: STRUCTURE.md (optional).

P — Plan (Tactical)

Exact sequence of atomic tasks with validation criteria. Every task MUST carry a verification marker:

  • [🔍 da verificare] — not yet confirmed by research
  • [🔍 confermato da: web-research/<file>.md] — confirmed by research artifact Design is NOT complete until ALL markers are confirmed. Output: PLAN.md.

Verification Loop

  1. Identify all unknowns → propose deep research prompts
  2. Save research results to web-research/
  3. Draft DESIGN.md and PLAN.md with markers
  4. For any unverified item → more research
  5. Repeat until every part of the plan is confirmed
  6. Only then pass to crisp-build

Project Hierarchy

Root projects use semantic names (e.g., hetzner-vault-platform). Subprojects use numeric prefixes (e.g., 10-, 20-, 30-). This is recursive: children of subprojects also use prefixes.

Only leaf (implementation) projects have web-research/ folders. Root projects maintain a web-research/INDEX.md tracking all research across the tree.

hetzner-vault-platform/
├── web-research/INDEX.md       (research index for the whole tree)
├── 10-hetzner-vault-foundation/     (parent — no research)
│   ├── 10-hetzner-runtime-golden-image/  (leaf — has web-research/)
│   └── 20-hetzner-tailscale-foundation/  (leaf — has web-research/)
├── 20-hetzner-vault-runtime/          (parent — no research)
└── 30-hetzner-vault-consumers/        (parent — no research)

Split Types

A project can be split in two ways:

  • Vertical (children): Parent becomes non-implementative, parent’s PLAN.md and web-research/ move to children.
  • Horizontal (siblings): One project becomes two same-level projects, research distributed between them.

No information may be lost during a split.

Build Handoff

Completed CRISP projects are handed to crisp-build for execution. When crisp-build creates tasks.md, granular tasks inherit markers from PLAN.md. Additional [🔍 da verificare] may be added if granular details need more research.

Completed projects are closed as historical artifacts — later changes belong in a new project, not reopened in the old one.

See Also