Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 36 additions & 30 deletions discovery-map/INDEX.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,47 +8,53 @@ A multi-phase initiative to add an **inception phase** at the start of every epi

## Phases

Each phase is its own PR off main, planned individually via plan mode.

1. **[Manifest Foundations](phase-01-manifest-foundations.md)** — `inception` phase + `imports` field validation in manifest CLI. **Status:** Not started
2. **[Inception MVP](phase-02-inception-mvp.md)** — entry/process skills, bridge continuation, start-epic wiring. **Status:** Not started
3. **[Discovery Map Render](phase-03-discovery-map-render.md)** — continue-epic display + menu collapse + auto-routing. **Status:** Not started
4. **[Refinement Session](phase-04-refinement-session.md)** — re-entry path, map editing operations, safety-by-destructiveness. **Status:** Not started
5. **[Self-Healing Re-point](phase-05-self-healing.md)** — research-analysis and gap-analysis re-point to map at continue-epic boot-up. **Status:** Not started
6. **[Imports](phase-06-imports.md)** — `imports/` directory, manifest tracking, KB indexing, behaviour change for features. **Status:** Not started
7. **[Topic Splitting and Elevation](phase-07-topic-splitting-elevation.md)** — write inception items alongside; name collision validation. **Status:** Not started
8. **[Direct-Entry Auto-Add](phase-08-direct-entry-auto-add.md)** — `d`/`discuss` and `r`/`research` for unmapped topics auto-create map items. **Status:** Not started
9. **[Migration](phase-09-migration.md)** — seed inception items for existing in-progress epics. **Status:** Not started
10. **[Drop Explore Mode](phase-10-drop-explore-mode.md)** — remove research's `e`/`explore`; collapse start-epic's `route-first-phase`. **Status:** Not started
11. **[Documentation Cleanup](phase-11-documentation.md)** — CLAUDE.md, README, phase tables, compliance checks. **Status:** Not started
Each phase is its own PR off the previous phase's branch (stacked PRs — see *Branching Strategy* below). Each phase is planned individually via plan mode when implementation begins.

1. **[Manifest Foundations](phase-01-manifest-foundations.md)** — `inception` phase + `imports` field validation in manifest CLI. **Status:** Done (PR #264)
2. **[Inception Entry Skill + Bridge Plumbing](phase-02-inception-entry-bridge.md)** — entry skill scaffold + bridge continuation + discovery.cjs awareness. **Status:** In progress
3. **[Inception Process Skill](phase-03-inception-process.md)** — the conversational inception session itself (initial-session flow). **Status:** Not started
4. **[Wire start-epic to Inception](phase-04-wire-start-epic.md)** — collapses the research/discussion menu; user-visible flip. **Status:** Not started
5. **[Discovery Map Render](phase-05-discovery-map-render.md)** — continue-epic display + menu collapse + auto-routing. **Status:** Not started
6. **[Refinement Session](phase-06-refinement-session.md)** — re-entry path, map editing operations, safety-by-destructiveness. **Status:** Not started
7. **[Self-Healing Re-point](phase-07-self-healing.md)** — research-analysis and gap-analysis re-point to map at continue-epic boot-up. **Status:** Not started
8. **[Imports](phase-08-imports.md)** — `imports/` directory, manifest tracking, KB indexing, behaviour change for features. **Status:** Not started
9. **[Topic Splitting and Elevation](phase-09-topic-splitting-elevation.md)** — write inception items alongside; name collision validation. **Status:** Not started
10. **[Direct-Entry Auto-Add](phase-10-direct-entry-auto-add.md)** — `d`/`discuss` and `r`/`research` for unmapped topics auto-create map items. **Status:** Not started
11. **[Migration](phase-11-migration.md)** — seed inception items for existing in-progress epics. **Status:** Not started
12. **[Drop Explore Mode](phase-12-drop-explore-mode.md)** — remove research's `e`/`explore`; collapse start-epic's `route-first-phase`. **Status:** Not started
13. **[Documentation Cleanup](phase-13-documentation.md)** — CLAUDE.md, README, phase tables, compliance checks. **Status:** Not started

## Dependencies

```
Phase 1 (manifest foundations)
└──▶ Phase 2 (inception MVP)
└──▶ Phase 2 (inception entry skill + bridge plumbing)
└──▶ Phase 3 (map render)
└──▶ Phase 3 (inception process skill)
├──▶ Phase 4 (refinement)
│ │
│ └──▶ Phase 5 (self-healing)
│ │
│ ├──▶ Phase 6 (imports — also depends on Phase 2)
│ │
│ ├──▶ Phase 7 (split/elevation)
│ │
│ └──▶ Phase 8 (direct-entry)
└──▶ Phase 9 (migration)
└──▶ Phase 4 (wire start-epic to inception)
└──▶ Phase 10 (drop explore mode)
└──▶ Phase 5 (map render)
├──▶ Phase 6 (refinement)
│ │
│ └──▶ Phase 7 (self-healing)
│ │
│ ├──▶ Phase 8 (imports — also depends on Phase 4)
│ │
│ ├──▶ Phase 9 (split/elevation)
│ │
│ └──▶ Phase 10 (direct-entry)
└──▶ Phase 11 (docs)
└──▶ Phase 11 (migration)
└──▶ Phase 12 (drop explore mode)
└──▶ Phase 13 (docs)
```

Phases 6, 7, 8 can be parallelised after Phase 5. Phases 9-11 sequence after the rest.
Phases 8, 9, 10 can be parallelised after Phase 7. Phases 11-13 sequence after the rest.

## Branching Strategy — Stacked PRs

Expand All @@ -58,7 +64,7 @@ To keep `main` clean of incomplete-feature work until the whole initiative is re
- **Phase 1** branches off `main` (after the planning branch has merged).
- **Phase 2** branches off Phase 1's branch (not main).
- **Phase 3** branches off Phase 2's branch.
- And so on through Phase 11.
- And so on through Phase 13.

Each phase's PR has its own scope and review. When the implementer is happy with all phases, the PRs merge in turn — Phase 1 first, then Phase 2 (rebased onto main if needed), then Phase 3, etc. — until the whole initiative lands.

Expand Down
4 changes: 2 additions & 2 deletions discovery-map/phase-01-manifest-foundations.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,8 @@ Foundation for everything that follows. Adds `inception` as a recognised phase a

## Out of scope

- Inception-related skills (Phase 2).
- Display of inception items in `continue-epic` (Phase 3).
- Inception-related skills (Phases 2-4).
- Display of inception items in `continue-epic` (Phase 5).
- Anything user-visible.

## Verification
Expand Down
77 changes: 77 additions & 0 deletions discovery-map/phase-02-inception-entry-bridge.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# Phase 2 — Inception Entry Skill + Bridge Plumbing

**Status:** Not started · **Depends on:** Phase 1

## Purpose

First slice of the original "Inception MVP" (split into Phases 2-4 for reviewable size).

Establishes the **inception door**: the entry-point skill that routes incoming work into inception, plus the bridge continuation that routes back out, plus minimal awareness in `continue-epic`'s discovery script. The room behind the door (the actual conversation) lands in Phase 3; wiring `start-epic` to walk through the door lands in Phase 4.

After this phase: `/workflow-inception-entry epic {wu}` is a registered, compliant skill that gathers context and would invoke a processing skill — but the processing skill doesn't exist yet, so end-to-end use isn't possible. **No user-visible behaviour change** — `/start-epic` still routes to research/discussion as it does today.

## Reference

- [Design](design.md) — *Inception Phase — Behaviour* → *Initial session* (lines 184-195) for the entry shape; *Files on disk* (lines 302-318).
- `CONVENTIONS.md` — **MANDATORY** before authoring any skill file. Display rules, Step 0 structure, load directive format, zero-output rule, reference-file structure.
- `skills/workflow-research-entry/SKILL.md` and references — closest precedent. Model the inception-entry skill on this shape.
- `skills/workflow-bridge/SKILL.md` and `references/epic-continuation.md` — pattern for the continuation reference. Inception's continuation is simpler — always re-invokes `/continue-epic {wu}` with no phase-routing computation.
- `skills/continue-epic/scripts/discovery.cjs` — line 5 (`EPIC_PHASES`) needs `inception` added so the iterators don't skip the new phase.

## What ships

- New skill `workflow-inception-entry/` (SKILL.md + 3 references). Models on `workflow-research-entry`.
- New `workflow-bridge/references/inception-continuation.md` — plan-mode handoff that re-invokes `/continue-epic {work_unit}`.
- `workflow-bridge/SKILL.md` — register the new continuation reference (`completed_phase = inception` route).
- `continue-epic/scripts/discovery.cjs` — add `'inception'` to `EPIC_PHASES`. **No display change** — Phase 5 owns the discovery-map render.

## Files

**New — `skills/workflow-inception-entry/`:**

- `SKILL.md` — backbone with Step 0 (initialisation), Step 1 (parse args — `$0`=work_type, `$1`=work_unit, `$2` unused since inception is per-work-unit), Step 2 (check phase entry), Step 3 (validate — first-session vs re-entry), Step 4 (gather context), Step 5 (invoke skill).
- `references/validate-phase.md` — **first-session vs re-entry detection.** Phase 2 only wires the first-session branch. Re-entry emits a "refinement coming in Phase 6" stub and returns. Phase 6 replaces the body.
- `references/gather-context.md` — minimal. Reads work-unit description from manifest. If `imports[]` is non-empty, lists filenames as additional context (Phase 8 broadens this — KB indexing on import).
- `references/invoke-skill.md` — handoff to `workflow-inception-process`. **Note:** the processing skill doesn't exist until Phase 3. For Phase 2, the handoff text is authored against the future skill name; invoking it will error until Phase 3 lands. This is fine — Phase 2's PR is reviewable in isolation, and the entry skill becomes useful when stacked atop Phase 3.

**New — `skills/workflow-bridge/references/inception-continuation.md`:**

- Plan-mode handoff that always re-invokes `/continue-epic {work_unit}`. No phase-routing computation needed (single deterministic outcome).

**Modified:**

- `skills/workflow-bridge/SKILL.md` — Step 2 routing table gains an `inception` branch. Place above the existing epic branch.
- `skills/continue-epic/scripts/discovery.cjs` — line 5: add `'inception'` to `EPIC_PHASES`. Verify `buildEpicDetail` doesn't error on `phases.inception.items.{topic}` shape (status only, no `sources`/`format`).

## Out of scope

- Inception process skill itself (Phase 3).
- Wiring `start-epic` to invoke inception (Phase 4).
- Discovery-map render in `continue-epic` (Phase 5).
- Refinement / re-entry implementation (Phase 6).
- Imports machinery beyond awareness in `gather-context.md` (Phase 8).

## Verification

1. Compliance self-check passes on `workflow-inception-entry/SKILL.md` and each reference file.
2. Direct invocation smoke test:
```bash
cd "$(mktemp -d)" && mkdir -p .workflows
# Manually init an epic for testing
node /path/to/skills/workflow-manifest/scripts/manifest.cjs init test-epic --work-type epic --description "Test"
# Invoke the entry skill (will error at Step 5 because process skill doesn't exist yet — expected for Phase 2)
/workflow-inception-entry epic test-epic
```
Expected: skill loads, runs Step 0 → Step 4 cleanly, then errors at Step 5 invoking the missing process skill. The error confirms wiring is in place.
3. `continue-epic` does not error on existing epics (which have no `inception` phase):
```bash
node skills/continue-epic/scripts/discovery.cjs
```
4. Run existing manifest tests to confirm Phase 1's foundations still pass.

## Notes for the implementer

- **CONVENTIONS.md is mandatory.** Re-read it before authoring `SKILL.md` and references — the conventions are dense and have produced silently non-compliant skills when relied on by memory.
- **Phase 2 is intentionally unreachable end-to-end.** The entry skill exists but invoking it will fail at Step 5 because Phase 3 hasn't shipped yet. This is by design — small, reviewable PRs build on each other.
- **Re-entry is stubbed, not skipped.** `validate-phase.md` has both branches structurally; the re-entry branch points to a Phase-6 placeholder. Phase 6 replaces the body with the real refinement flow. No throwaway code.
- **No background agents.** Inception is curatorial; Phase 3's process skill won't dispatch review/perspective agents either.
82 changes: 0 additions & 82 deletions discovery-map/phase-02-inception-mvp.md

This file was deleted.

Loading