Skip to content

Commit f04d494

Browse files
committed
docs: clarify existing vs new functionality in artifact_poc.md
Audit artifact_poc.md against existing codebase to mark what already exists vs what's genuinely new: - Slice 4 CLI table: Added Status column (NEW/EXISTS) - Added "Existing CLI commands" section listing what's not in scope - Updated Implementation Order Slice 4 with explicit new vs existing - Summary table: Updated status + added "What already exists" section Key finding: The document was already well-simplified. Only truly new functionality (createChange, validateChangeName, InstructionLoader, artifact graph CLI commands) is proposed.
1 parent f59d9a9 commit f04d494

File tree

1 file changed

+42
-15
lines changed

1 file changed

+42
-15
lines changed

docs/artifact_poc.md

Lines changed: 42 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -211,18 +211,24 @@ ChangeState {
211211

212212
User interface layer. **All commands are deterministic** - require explicit `--change` parameter.
213213

214-
| Command | Function |
215-
|---------|----------|
216-
| `status --change <id>` | Show change progress |
217-
| `next --change <id>` | Show artifacts ready to create |
218-
| `instructions <artifact> --change <id>` | Get enriched instructions for artifact |
219-
| `list` | List all changes |
220-
| `new <name>` | Create change |
221-
| `init` | Initialize structure |
222-
| `templates --change <id>` | Show resolved template paths |
214+
| Command | Function | Status |
215+
|---------|----------|--------|
216+
| `status --change <id>` | Show change progress (artifact graph) | **NEW** |
217+
| `next --change <id>` | Show artifacts ready to create | **NEW** |
218+
| `instructions <artifact> --change <id>` | Get enriched instructions for artifact | **NEW** |
219+
| `list` | List all changes | EXISTS (`openspec change list`) |
220+
| `new <name>` | Create change | **NEW** (uses `createChange()`) |
221+
| `init` | Initialize structure | EXISTS (`openspec init`) |
222+
| `templates --change <id>` | Show resolved template paths | **NEW** |
223223

224224
**Note:** Commands that operate on a change require `--change`. Missing parameter → error with list of available changes. Agent infers the change from conversation and passes it explicitly.
225225

226+
**Existing CLI commands** (not part of this slice):
227+
- `openspec change list` / `openspec change show <id>` / `openspec change validate <id>`
228+
- `openspec list --changes` / `openspec list --specs`
229+
- `openspec view` (dashboard)
230+
- `openspec init` / `openspec archive <change>`
231+
226232
---
227233

228234
### 5. Claude Commands
@@ -453,10 +459,23 @@ Structured as **vertical slices** - each slice is independently testable.
453459

454460
### Slice 4: "CLI + Integration"
455461

456-
**Delivers:** Full command interface
462+
**Delivers:** New artifact graph commands (builds on existing CLI)
463+
464+
**New commands:**
465+
- `status --change <id>` - Show artifact completion state
466+
- `next --change <id>` - Show ready-to-create artifacts
467+
- `instructions <artifact> --change <id>` - Get enriched template
468+
- `templates --change <id>` - Show resolved paths
469+
- `new <name>` - Create change (wrapper for `createChange()`)
470+
471+
**Already exists (not in scope):**
472+
- `openspec change list/show/validate` - change management
473+
- `openspec list --changes/--specs` - listing
474+
- `openspec view` - dashboard
475+
- `openspec init` - initialization
457476

458477
**Testable behaviors:**
459-
- Each command produces expected output
478+
- Each new command produces expected output
460479
- Commands compose correctly (status → next → instructions flow)
461480
- Error handling for missing changes, invalid artifacts, etc.
462481

@@ -551,12 +570,20 @@ artifacts:
551570
552571
| Layer | Component | Responsibility | Status |
553572
|-------|-----------|----------------|--------|
554-
| Core | ArtifactGraph | Pure dependency logic + XDG schema resolution | ✅ Slice 1 |
555-
| Utils | change-utils | Change creation + name validation | Slice 2 |
556-
| Core | InstructionLoader | Template resolution + enrichment | Slice 3 |
557-
| Presentation | CLI | Thin command wrapper | Slice 4 |
573+
| Core | ArtifactGraph | Pure dependency logic + XDG schema resolution | ✅ Slice 1 COMPLETE |
574+
| Utils | change-utils | Change creation + name validation only | Slice 2 (new functionality only) |
575+
| Core | InstructionLoader | Template resolution + enrichment | Slice 3 (all new) |
576+
| Presentation | CLI | New artifact graph commands | Slice 4 (new commands only) |
558577
| Integration | Claude Commands | AI assistant glue | Slice 4 |
559578
579+
**What already exists (not in this proposal):**
580+
- `getActiveChangeIds()` in `src/utils/item-discovery.ts` - list changes
581+
- `ChangeCommand.list/show/validate()` in `src/commands/change.ts`
582+
- `ListCommand.execute()` in `src/core/list.ts`
583+
- `ViewCommand.execute()` in `src/core/view.ts` - dashboard
584+
- `src/core/init.ts` - initialization
585+
- `src/core/archive.ts` - archiving
586+
560587
**Key Principles:**
561588
- **Filesystem IS the database** - stateless, version-control friendly
562589
- **Dependencies are enablers** - show what's possible, don't force order

0 commit comments

Comments
 (0)