ADR-208: Research-to-Product Promotion Lifecycle

Status

Accepted — 2026-02-16

Context

Problem Statement

ADR-207 established a 6-category taxonomy and YAML manifest system for organizing 96+ research staging directories into coditect-core. It covers document-level artifacts (SDDs, TDDs, executive summaries, glossaries, C4 models, dashboards) and their promotion into permanent directories.

However, ADR-207's scope ends at document promotion. Research efforts frequently evolve beyond documents into:

• Full products — standalone applications with their own repositories, deployment pipelines, and customer-facing features (e.g., sidecar research → coditect-development-studio)
• Prototypes / test beds — experimental implementations that validate feasibility before product commitment (e.g., coditect-nested-learning)
• Framework components — new agents, skills, commands, or workflows absorbed directly into coditect-core (e.g., bio-QMS research → bio-qms-agent-framework skill)
• Dead ends — research that produces valuable lessons but no viable path forward (e.g., AGPL-licensed dependencies with no clean-room alternative)

Without a formalized decision gate, the transition from "research with documents" to "this becomes something real" happens ad-hoc, leading to:

• Inconsistent artifact locations across submodules
• Missing projects.db registrations for new products
• No manifest trail linking products back to their originating research
• Lost lessons learned from rejected research

Relationship to ADR-206 and ADR-207

ADR	Scope	Lifecycle Coverage
ADR-206	Research pipeline — how research is conducted	Input → Staging
ADR-207	Document taxonomy — how artifacts are categorized and promoted	Staging → Integration (documents only)
ADR-208	Product lifecycle — how research becomes products, prototypes, or components	Integration → Product/Prototype/Component/Archive

ADR-208 extends the manifest schema from ADR-207 with product-level promotion fields and formalizes the triage decision framework.

Decision

1. Four Terminal Outcomes

Every research effort in the staging pipeline (analyze-new-artifacts/) eventually reaches one of four terminal outcomes:

Outcome	Manifest Value	Destination	Governance
Product	outcome: product	submodules/products/ or submodules/dev/	Own repo, TRACK entries, projects.db registration
Prototype	outcome: prototype	submodules/labs/prototypes/	Experimental, no SLA, may graduate to product
Component	outcome: component	coditect-core (agents/, skills/, commands/, workflows/)	Framework governance, standard PR process
Archive	outcome: archive	internal/research/archive/	Read-only reference with lessons learned

A fifth non-terminal state exists:

State	Manifest Value	Meaning
Monitor	outcome: monitor	Not yet triaged — awaiting evaluation

2. Decision Framework

The triage decision uses the manifest's recommendation field (from ADR-207) plus new criteria:

ADOPT + standalone value + customer-facing  → Product
ADOPT + standalone value + experimental     → Prototype
ADOPT + no standalone value + framework-fit → Component
DEFER                                       → Monitor (re-evaluate later)
REJECT                                      → Archive

Decision criteria in detail:

Criterion	Product	Prototype	Component	Archive
Standalone deployable?	Yes	Yes	No	N/A
Customer-facing?	Yes	Not yet	Indirect	No
Revenue potential?	Yes/Planned	Uncertain	No	No
Needs own repo?	Yes	Yes	No	No
License compatible?	Yes	Yes	Yes	Blocked
Technical feasibility?	Proven	Unproven	Proven	Failed/Blocked

3. Manifest Schema Extension

ADR-207 manifests gain new optional fields for product-level promotion:

# ADR-207 fields (unchanged)
research_id: "2026-01-15-scaling-agent-systems"
topic: "scaling-agent-systems"
category: "technology-evaluation"
recommendation: ADOPT
confidence: HIGH

# ADR-208 extensions
outcome: product                              # product | prototype | component | archive | monitor
outcome_date: "2026-02-16"                    # When the outcome was decided
outcome_rationale: "Proven architecture, clear GTM path, investor interest"

# Product-specific
product:
  repository: "submodules/products/coditect-runway-calculator"
  project_id: "coditect-runway-calculator"     # projects.db registration
  track_tasks: ["N.3.1", "N.3.2", "N.3.3"]   # TRACK entries created
  launch_target: "2026-Q1"

# Prototype-specific
prototype:
  repository: "submodules/labs/prototypes/coditect-nested-learning"
  graduation_criteria:
    - "Pass 3 user validation sessions"
    - "Sub-2s response time at 100 concurrent users"
    - "License audit clean"
  graduation_target: "2026-Q2"

# Component-specific
component:
  type: skill                                  # agent | skill | command | workflow
  name: "bio-qms-agent-framework"
  description: "Brief description of what this component does"
  path: "skills/bio-qms-agent-framework/SKILL.md"  # Set when component is created (Phase 2)
  track_tasks: ["AB.1.1"]                           # Empty [] until implementation begins
  source_repo: "https://github.com/example/repo"    # External source being integrated (if any)
  source_license: "MIT"                              # License of external source

# Archive-specific
archive:
  reason: "AGPL license incompatible with proprietary distribution"
  lessons_learned:
    - "Check license compatibility BEFORE deep technical analysis"
    - "AGPL requires process boundary separation — document in ADR"
  reusable_artifacts:
    - "Architecture patterns documented in SDD still applicable"
    - "Benchmark data reusable for future evaluations"
  archived_date: "2026-02-16"

4. Promotion Workflows

Research → Product

1. Update manifest: recommendation=ADOPT, outcome=product
2. Create repository under submodules/products/ or submodules/dev/
3. Register in projects.db: /register-project <name>
4. Add TRACK entries (typically Track N for GTM, or domain-specific track)
5. Promote documents (ADR-207 pipeline) — SDD, TDD, executive summary
6. Create ADRs for key architectural decisions
7. Update manifest with product.repository, product.project_id, product.track_tasks
8. Archive staging directory (move to internal/research/archive/ or leave in place)

Research → Prototype

1. Update manifest: recommendation=ADOPT, outcome=prototype
2. Create repository under submodules/labs/prototypes/
3. Define graduation criteria in manifest
4. Lightweight governance — no projects.db registration yet
5. Set graduation target date
6. Re-evaluate at graduation target → graduate to Product or Archive

Research → Component

Component promotion happens in two phases. Phase 1 (triage) promotes documents and records the outcome decision. Phase 2 (implementation) builds the actual component when development begins.

Phase 1 — Triage (immediate):
1. Update manifest: recommendation=ADOPT, outcome=component
2. Promote documents via ADR-207 pipeline (SDD, TDD, executive summary, etc.)
3. Set component.type, component.name, component.description in manifest
4. Set component.track_tasks=[] and omit component.path (not yet created)
5. If external source: set component.source_repo and component.source_license

Phase 2 — Implementation (when development begins):
6. Create agent/skill/command/workflow: /component-create <type> <name>
7. Add TRACK entry for the component work
8. Update manifest: component.path, component.track_tasks
9. Run /classify on new component

Research-specific ADRs: If the staging artifacts include research-scoped ADRs (e.g., ADR-001 through ADR-005 within the research context), promote them to internal/architecture/c4-models/{topic}/adrs/. These are distinct from framework-level ADRs in internal/architecture/adrs/ — they document decisions specific to the research effort's integration approach.

Research → Archive

1. Update manifest: recommendation=REJECT, outcome=archive
2. Document rejection reason and lessons learned in manifest
3. Identify reusable artifacts (data, patterns, benchmarks)
4. Move staging directory contents to internal/research/archive/<topic>/
5. Update master registry (internal/research/manifests/README.md)

5. Prototype Graduation

Prototypes have a built-in re-evaluation gate:

Prototype created
    ↓ graduation_target date reached
Re-evaluate against graduation_criteria
    ↓
├── All criteria met → Graduate to Product (workflow 4a above)
├── Partial progress → Extend graduation_target
└── No viable path   → Archive (workflow 4d above)

6. Manifest Registry Updates

The master registry at internal/research/manifests/README.md gains an Outcomes section:

## Outcomes Summary

| Outcome | Count | Examples |
|---------|-------|---------|
| Product | 3 | coditect-runway-calculator, coditect-development-studio, ... |
| Prototype | 2 | coditect-nested-learning, ... |
| Component | 5 | bio-qms-agent-framework, ... |
| Archive | 12 | ... |
| Monitor | 74 | (pending triage) |

Consequences

Positive

• Traceability: Every product, prototype, and component traces back to its originating research via manifest linkage
• Lessons preserved: Archived research captures rejection reasons and reusable artifacts, preventing repeated dead-end investigations
• Consistent governance: Products get projects.db registration, prototypes get graduation criteria, components follow framework standards
• Decision audit trail: The manifest records when, why, and by whom the outcome was decided

Negative

• Manifest maintenance: Product-level fields add complexity to the YAML schema
• Process overhead: Formalizing previously ad-hoc decisions adds steps (though prevents missed registrations)

Neutral

• Backward compatible: All ADR-208 fields are optional extensions to existing ADR-207 manifests — no migration required
• 96 existing manifests: Currently all at outcome: monitor — triage happens incrementally as research is evaluated

Alternatives Considered

1. Extend ADR-207 directly

Rejected — ADR-207 is focused on document taxonomy. Product lifecycle is a distinct concern that warrants its own decision record.

2. No formalization (continue ad-hoc)

Rejected — the current ad-hoc approach works for small numbers but doesn't scale. With 96 research efforts, missing registrations and lost lessons learned become likely.

3. Separate tracking system outside manifests

Rejected — the YAML manifest is already the SSOT for each research effort. Adding product-level fields keeps everything in one place rather than splitting context.

Implementation

Phase 1: Schema Extension (this ADR)

• Add optional outcome, outcome_date, outcome_rationale fields to manifest schema
• Add product, prototype, component, archive sub-schemas
• Update config/schemas/research-manifest-v1.schema.json → v1.1.0
• No migration needed — new fields are optional

Phase 2: Backfill Existing Outcomes

• Identify research efforts that already became products/prototypes/components
• Update their manifests with the appropriate outcome fields
• Known existing outcomes:
  • codestoryai-sidecar → informed coditect-development-studio (product)
  • bio-qms-* → bio-qms-agent-framework skill (component)
  • coditect-nested-learning → prototype in submodules/labs/prototypes/

Phase 3: Triage Automation (future)

• /research-triage <topic> command for interactive outcome selection
• Auto-generates projects.db registration for product outcomes
• Auto-creates TRACK entries for product/component outcomes
• Updates manifest and registry atomically

Related Decisions

• ADR-206: Autonomous Research Pipeline (how research is conducted)
• ADR-207: Research Artifact Organization Taxonomy (document promotion)
• ADR-116: Track-Based Plan Architecture (TRACK task governance)
• ADR-155: Project-Scoped Session Logs (project registration)

---

Decision Date: 2026-02-16 Decided By: Hal Casteel, Claude (Opus 4.6) Supersedes: None Superseded By: None