Proof of Concept mode
Project mode is separate from project state. State describes the repository (new, pre-ai, or
legacy); mode describes how Kaddo should guide the work.
Use poc when the immediate goal is to validate an assumption, not to plan a complete product
roadmap.
kaddo init --mode poc# or, for an existing projectkaddo project mode pockaddo add agentskaddo add skillsExisting projects remain in standard mode when project.mode is absent.
POC route
flowchart LR A[Enable Kaddo] --> B[Hypothesis] B --> C[Success criteria] C --> D[Minimal technical context] D --> E[Resources] E --> F[Experiment Work Item] F --> G[Evidence] G --> H[Conclusion] H --> I["Final report (optional)"]
The canonical artifact is knowledge/delivery/poc.md. It records:
- Problem
- Hypothesis
- Expected Value
- Scenario
- Success Criteria
- Constraints
- Non-goals
- Evidence
- Conclusion:
validated,rejected, orinconclusive
POC template
Create knowledge/delivery/poc.md from this template, then replace every placeholder with
experiment-specific evidence. Keep the conclusion as pending until the evidence has been reviewed.
---type: pocstatus: activegenerated_by: kaddo-inittemplate_version: 1---
# <Project name> — Proof of Concept
## Problem
_What are we trying to understand or solve?_
## Hypothesis
_What assumption are we testing?_
## Expected Value
_Why is validating this worth doing?_
## Scenario
_What concrete scenario will demonstrate the hypothesis?_
## Success Criteria
- [ ] _Observable result that would support the hypothesis._
## Constraints
_Technical, time, budget, compliance, or operational constraints._
## Non-goals
_What this experiment intentionally will not prove or deliver._
## Evidence
_Link experiments, Work Items, measurements, and observations here._
## Conclusion
Status: pendingPOC mode is ready after initialization: define the hypothesis and success criteria in poc.md,
then create a spike when the experiment is clear. It does not require the standard
Business/Product baseline, a roadmap, or a complete capability map. Add technical context and
Project Resources only when the experiment needs them.
Install agents and skills during the initial POC setup. They provide the guided refinement and implementation context without creating a standard Business/Product baseline.
Run kaddo understand, kaddo context, or inspect kaddo://poc through MCP to see the current
POC status and the next recommended step.
Final POC report
poc.md remains the working and canonical experiment artifact. A final report is an optional,
immutable communication snapshot created only after the conclusion is validated, rejected, or
inconclusive. It never blocks POC completion or changes the canonical conclusion.
kaddo poc reportThe command prepares deterministic, source-attributed context; it does not call an LLM or write a
report. An agent synthesizes a proposal from that context, a human reviews it, and Core persists a
confirmed report next to poc.md as poc-report-v001.md, then poc-report-v002.md, and so on.
Earlier versions are never overwritten.
Kaddo records a fingerprint of the exact selected sources. The report is missing, current, or
stale; new evidence makes it stale but never regenerates it automatically. Regeneration creates
the next version only after an explicit confirmation. The context includes poc.md and only
directly traceable experiment Work Items, evidence, referenced Resources, Tech knowledge, and
decisions. It excludes credential values, tokens, private keys, passwords, and connection strings.
The report uses this canonical structure:
- Executive Summary
- Problem and Objective
- Hypothesis and Success Criteria
- Scope, Constraints and Non-goals
- Technical Approach and Architecture
- Infrastructure and Project Resources
- Implementation and Relevant Technical Decisions
- Experiments and Validation
- Results and Measurements
- Cost and Efficiency Analysis
- Observability and Operational Findings
- Findings, Learnings, Limitations and Risks
- Conclusion
- Recommendation and Next Steps
- Traceability and Sources
Evidence-driven representation
Choose the form that communicates the supplied evidence most clearly. Tables and diagrams are communication tools, not completeness requirements: do not add either one just to make a report look more complete. Use prose for context and interpretation, Markdown tables for comparable evidence, and Mermaid for grounded architecture, topology, or flows. Do not invent rows, metrics, priorities, components, or relationships. Prefer Mermaid to an ASCII diagram when both can express the same grounded flow.
| Section | Preferred representation when supported by evidence |
|---|---|
| Executive Summary | Snapshot table and short prose |
| Problem and Objective | Prose |
| Hypothesis and Success Criteria | Evaluation matrix |
| Scope, Constraints and Non-goals | Compact bullets or table |
| Technical Approach and Architecture | Mermaid and prose |
| Infrastructure and Project Resources | Table, with optional Mermaid |
| Implementation and Relevant Technical Decisions | Table or concise prose |
| Experiments and Validation | Validation matrix |
| Results and Measurements | Measurement tables |
| Cost and Efficiency Analysis | Comparison table |
| Observability and Operational Findings | Table or prose |
| Findings, Learnings, Limitations and Risks | Structured matrix |
| Conclusion | Status and concise prose |
| Recommendation and Next Steps | Recommendation matrix when priority is evidenced |
| Traceability and Sources | Relative-link table or list |
For example, a success-criteria matrix is useful when each outcome has direct evidence:
| Success criterion | Status | Evidence |
|---|---|---|
| API endpoint available | Passed | End-to-end verification |
| Three scenarios validated | Passed | 3/3 recorded results |
When selected sources describe a real relationship or flow, use a grounded Mermaid diagram:
flowchart LR Client --> API API --> Rules Rules --> Result
Likewise, Project Resources are easier to scan as a table when the sources provide comparable attributes:
| Resource | Type / provider | Purpose | Environment |
|---|---|---|---|
RES-model | AI provider | Model inference | poc |
RES-monitoring | Monitoring service | Experiment observability | poc |
Traceability must remain portable across GitHub, Kaddo Admin, and local clones. Use
repository-relative links such as [POC definition](./poc.md) or
[WI-001](./work-items/completed/WI-001.md), never file:/// URLs or local absolute paths.
Sections without evidence state Not evaluated in this POC., Not applicable., or No evidence available. rather than inventing data. A report can recommend graduation to standard mode, but
the human decides whether to run kaddo project mode standard.
Graduate or finish
When evidence supports a durable delivery effort, switch back to the standard flow and bootstrap the remaining baseline:
kaddo project mode standardkaddo bootstrapWhen evidence rejects or cannot establish the hypothesis, record the conclusion in poc.md and
keep the decision trace without creating unnecessary product planning artifacts.