fix: use import type for GraphConfig, remove verbatim-module-syntax exclusion
The verbatim-module-syntax lint rule was correctly flagging that GraphConfig is only used in a type position (typeof GraphConfig). Since typeof resolves purely at the type level, import type works fine here and is the correct form. No lint exclusion needed. Also: deno fmt across all files (markdown line wrapping).
This commit is contained in:
@@ -2,9 +2,12 @@
|
||||
|
||||
## Overview
|
||||
|
||||
This document defines the SDD process for the @alkdev/storage package. It leverages:
|
||||
This document defines the SDD process for the @alkdev/storage package. It
|
||||
leverages:
|
||||
|
||||
- **OpenCode CLI** as the agent execution environment
|
||||
- **Open-coordinator plugin** for worktree management and parallel session orchestration
|
||||
- **Open-coordinator plugin** for worktree management and parallel session
|
||||
orchestration
|
||||
- **Structured task graphs** with dependency analysis and safe exit protocols
|
||||
|
||||
## Core Principles
|
||||
@@ -14,29 +17,37 @@ This document defines the SDD process for the @alkdev/storage package. It levera
|
||||
3. **Flexible Self**: Agents can implement, self-review, and fix objectively
|
||||
4. **Task-Driven**: Structured task graphs with dependency analysis
|
||||
5. **Safe Exit**: Always have a way to unblock progress when stuck
|
||||
6. **Categorical Estimates**: Use risk/scope/impact categories, not time estimates. These are structurally important — upstream failures multiply downstream damage regardless of developer type (human or LLM). See the cost-benefit framework in taskgraph's framework docs.
|
||||
6. **Categorical Estimates**: Use risk/scope/impact categories, not time
|
||||
estimates. These are structurally important — upstream failures multiply
|
||||
downstream damage regardless of developer type (human or LLM). See the
|
||||
cost-benefit framework in taskgraph's framework docs.
|
||||
|
||||
## Workflow Phases
|
||||
|
||||
### Phase 0: Exploration (Conditional)
|
||||
|
||||
**When**: Requirements unclear, multiple approaches to evaluate, or hard problems need investigation.
|
||||
**When**: Requirements unclear, multiple approaches to evaluate, or hard
|
||||
problems need investigation.
|
||||
|
||||
**Process**:
|
||||
|
||||
1. Capture vision and guiding principles
|
||||
2. Research Specialist investigates options (`docs/research/` or external)
|
||||
3. POC Specialist validates promising approaches (`.worktrees/research/`)
|
||||
4. Document learnings
|
||||
5. Converge on recommended approach
|
||||
|
||||
**Output**: Clear understanding of WHAT to build and WHY, with validated approaches
|
||||
**Output**: Clear understanding of WHAT to build and WHY, with validated
|
||||
approaches
|
||||
|
||||
### Phase 1: Architecture
|
||||
|
||||
**Objective**: Produce comprehensive, committed architecture specification.
|
||||
|
||||
**Process**:
|
||||
1. Architect creates modular architecture docs in `docs/architecture/` (Draft status)
|
||||
|
||||
1. Architect creates modular architecture docs in `docs/architecture/` (Draft
|
||||
status)
|
||||
2. Architecture Review validates for ambiguities, risks
|
||||
3. Iterate until zero critical issues
|
||||
4. Transition to Stable status
|
||||
@@ -48,6 +59,7 @@ This document defines the SDD process for the @alkdev/storage package. It levera
|
||||
**Objective**: Break architecture into atomic, dependency-ordered tasks.
|
||||
|
||||
**Process**:
|
||||
|
||||
1. Decomposer analyzes architecture
|
||||
2. Creates tasks (markdown files in `tasks/`)
|
||||
3. Establishes dependencies between tasks
|
||||
@@ -61,14 +73,18 @@ This document defines the SDD process for the @alkdev/storage package. It levera
|
||||
**Objective**: Execute tasks in dependency order with verification.
|
||||
|
||||
**Process**:
|
||||
|
||||
1. Coordinator identifies parallelizable work
|
||||
2. Coordinator spawns worktrees + sessions (via `worktree({action: "spawn", ...})` or hub `coord.spawn` when available)
|
||||
2. Coordinator spawns worktrees + sessions (via
|
||||
`worktree({action: "spawn", ...})` or hub `coord.spawn` when available)
|
||||
- Feature work: `.worktrees/feat/<task-id>/` → Implementation Specialist
|
||||
- Research POCs: `.worktrees/research/<task-id>/` → POC Specialist
|
||||
3. Coordinator injects task context into each session
|
||||
4. Agents execute tasks with self-verification
|
||||
5. On completion: agent notifies coordinator, updates task status, commits to worktree branch
|
||||
6. On blocker: Safe Exit protocol, agent notifies coordinator, create blocker task
|
||||
5. On completion: agent notifies coordinator, updates task status, commits to
|
||||
worktree branch
|
||||
6. On blocker: Safe Exit protocol, agent notifies coordinator, create blocker
|
||||
task
|
||||
7. Merge worktrees back to main when complete
|
||||
|
||||
**Output**: Completed, verified implementation
|
||||
@@ -78,6 +94,7 @@ This document defines the SDD process for the @alkdev/storage package. It levera
|
||||
**Objective**: Validate quality and readiness.
|
||||
|
||||
**Process**:
|
||||
|
||||
1. Code review at injected checkpoints
|
||||
2. Final integration testing
|
||||
3. Architecture sync check
|
||||
@@ -96,16 +113,19 @@ This document defines the SDD process for the @alkdev/storage package. It levera
|
||||
**Mode**: Primary (interactive with user)
|
||||
|
||||
**Tools**:
|
||||
|
||||
- Read, Write, Edit, Glob, Grep
|
||||
- webSearch (research patterns, best practices)
|
||||
|
||||
**Key Behaviors**:
|
||||
|
||||
- Focus on WHAT and WHY, never HOW
|
||||
- Document decisions with ADR format
|
||||
- Redirect exploration work to Research Specialist
|
||||
- Iterate based on review feedback
|
||||
|
||||
**Deliverables**:
|
||||
|
||||
- Modular architecture docs in `docs/architecture/`
|
||||
- Component-specific documents
|
||||
|
||||
@@ -118,15 +138,18 @@ This document defines the SDD process for the @alkdev/storage package. It levera
|
||||
**Mode**: Primary (interactive with user for approval)
|
||||
|
||||
**Tools**:
|
||||
|
||||
- Read, Glob, Grep
|
||||
|
||||
**Key Behaviors**:
|
||||
|
||||
- Decompose to atomic tasks (single objective, clear acceptance criteria)
|
||||
- Establish logical dependencies
|
||||
- Validate structure (no cycles, logical ordering)
|
||||
- Inject review tasks at critical points
|
||||
|
||||
**Deliverables**:
|
||||
|
||||
- Task files in `tasks/` directory
|
||||
- Dependency graph validated
|
||||
|
||||
@@ -134,19 +157,27 @@ This document defines the SDD process for the @alkdev/storage package. It levera
|
||||
|
||||
#### 3. Coordinator
|
||||
|
||||
**Responsibility**: Orchestrate parallel task execution across worktrees and sessions.
|
||||
**Responsibility**: Orchestrate parallel task execution across worktrees and
|
||||
sessions.
|
||||
|
||||
**Mode**: Primary (manages worktrees and agent sessions)
|
||||
|
||||
**Uses**: The `worktree` tool from the **open-coordinator** opencode plugin. Single tool with `{action, args}` dispatch. Role is auto-detected — coordinator sessions get the full operation set, spawned implementation sessions get a limited set (current, notify, status). No mode toggle required.
|
||||
**Uses**: The `worktree` tool from the **open-coordinator** opencode plugin.
|
||||
Single tool with `{action, args}` dispatch. Role is auto-detected — coordinator
|
||||
sessions get the full operation set, spawned implementation sessions get a
|
||||
limited set (current, notify, status). No mode toggle required.
|
||||
|
||||
**Tools**:
|
||||
- `worktree({action, args})` — spawn, sessions, dashboard, message, abort, cleanup
|
||||
|
||||
- `worktree({action, args})` — spawn, sessions, dashboard, message, abort,
|
||||
cleanup
|
||||
- Bash (opencode CLI for session interaction)
|
||||
- Read (monitor task files)
|
||||
- `memory` / `memory_compact` — context management and session history (via @alkdev/open-memory, when available)
|
||||
- `memory` / `memory_compact` — context management and session history (via
|
||||
@alkdev/open-memory, when available)
|
||||
|
||||
**Key Behaviors**:
|
||||
|
||||
- Identify parallelizable task groups
|
||||
- Spawn worktrees + sessions via `worktree({action: "spawn", ...})`
|
||||
- Inject task context into sessions
|
||||
@@ -155,6 +186,7 @@ This document defines the SDD process for the @alkdev/storage package. It levera
|
||||
- Merge completed worktrees
|
||||
|
||||
**Deliverables**:
|
||||
|
||||
- Coordinated parallel execution
|
||||
- Blocked task escalation
|
||||
- Merged branches
|
||||
@@ -168,13 +200,16 @@ This document defines the SDD process for the @alkdev/storage package. It levera
|
||||
**Mode**: Primary (works on assigned task in worktree)
|
||||
|
||||
**Tools**:
|
||||
|
||||
- Read, Write, Edit, Glob, Grep, Bash
|
||||
- `worktree({action: "notify", ...})` — report progress/blockers to coordinator
|
||||
- `worktree({action: "current"})` — verify worktree assignment
|
||||
- webSearch (documentation lookup)
|
||||
- `memory` / `memory_compact` — context management (via @alkdev/open-memory, when available)
|
||||
- `memory` / `memory_compact` — context management (via @alkdev/open-memory,
|
||||
when available)
|
||||
|
||||
**Key Behaviors**:
|
||||
|
||||
- Load task context (architecture, dependencies)
|
||||
- Propose plan before implementing
|
||||
- Implement following architecture constraints
|
||||
@@ -184,6 +219,7 @@ This document defines the SDD process for the @alkdev/storage package. It levera
|
||||
- Commit to worktree branch
|
||||
|
||||
**Deliverables**:
|
||||
|
||||
- Completed task implementation
|
||||
- Tests passing
|
||||
- Committed changes in worktree
|
||||
@@ -199,9 +235,11 @@ This document defines the SDD process for the @alkdev/storage package. It levera
|
||||
**Mode**: Subagent (invoked by Architect)
|
||||
|
||||
**Tools**:
|
||||
|
||||
- Read, Grep
|
||||
|
||||
**Key Behaviors**:
|
||||
|
||||
- Check for undefined terms
|
||||
- Identify missing trade-off documentation
|
||||
- Validate quality attribute coverage
|
||||
@@ -216,9 +254,11 @@ This document defines the SDD process for the @alkdev/storage package. It levera
|
||||
**Mode**: Subagent (invoked by Coordinator or as task)
|
||||
|
||||
**Tools**:
|
||||
|
||||
- Read, Grep, Bash (lint, test)
|
||||
|
||||
**Key Behaviors**:
|
||||
|
||||
- Check adherence to architecture
|
||||
- Validate patterns and conventions
|
||||
- Run linters and tests
|
||||
@@ -233,10 +273,12 @@ This document defines the SDD process for the @alkdev/storage package. It levera
|
||||
**Mode**: Subagent (invoked by any role)
|
||||
|
||||
**Tools**:
|
||||
|
||||
- Read, Write, Glob
|
||||
- webSearch (primary research tool)
|
||||
|
||||
**Key Behaviors**:
|
||||
|
||||
- Find and summarize documentation
|
||||
- Evaluate library alternatives
|
||||
- Document findings
|
||||
@@ -245,17 +287,20 @@ This document defines the SDD process for the @alkdev/storage package. It levera
|
||||
|
||||
#### 8. POC Specialist
|
||||
|
||||
**Responsibility**: Create proof-of-concepts to validate technical approaches before production implementation.
|
||||
**Responsibility**: Create proof-of-concepts to validate technical approaches
|
||||
before production implementation.
|
||||
|
||||
**Mode**: Primary (works in isolated research worktree)
|
||||
|
||||
**Worktree Location**: `.worktrees/research/<task-id>/`
|
||||
|
||||
**Tools**:
|
||||
|
||||
- Read, Write, Edit, Glob, Grep, Bash
|
||||
- webSearch (implementation references)
|
||||
|
||||
**Key Behaviors**:
|
||||
|
||||
- Create minimal POCs to validate hypotheses
|
||||
- Work in isolated research worktrees
|
||||
- Document findings and recommendations
|
||||
@@ -263,11 +308,13 @@ This document defines the SDD process for the @alkdev/storage package. It levera
|
||||
- Be honest about limitations and blockers
|
||||
|
||||
**When Invoked**:
|
||||
|
||||
- After Research Specialist completes initial research
|
||||
- When a technical approach needs validation before commitment
|
||||
- When integration complexity or performance is uncertain
|
||||
|
||||
**Deliverables**:
|
||||
|
||||
- Working POC code
|
||||
- Findings document with recommendation (proceed/pivot/block)
|
||||
- Updated research task with results
|
||||
@@ -276,7 +323,8 @@ This document defines the SDD process for the @alkdev/storage package. It levera
|
||||
|
||||
## Task File Format
|
||||
|
||||
Tasks are markdown files stored in `tasks/`. Since they're in the repo, they're automatically available in worktrees.
|
||||
Tasks are markdown files stored in `tasks/`. Since they're in the repo, they're
|
||||
automatically available in worktrees.
|
||||
|
||||
```markdown
|
||||
---
|
||||
@@ -306,40 +354,46 @@ Implement OAuth2 authentication with provider abstraction.
|
||||
|
||||
## Notes
|
||||
|
||||
> Agent fills this during implementation. Document any decisions,
|
||||
> deviations from architecture, or relevant context discovered.
|
||||
> Agent fills this during implementation. Document any decisions, deviations
|
||||
> from architecture, or relevant context discovered.
|
||||
|
||||
## Summary
|
||||
|
||||
> Agent fills this on completion. Brief description of what was
|
||||
> implemented, files changed, and any follow-up needed.
|
||||
> Agent fills this on completion. Brief description of what was implemented,
|
||||
> files changed, and any follow-up needed.
|
||||
```
|
||||
|
||||
### Categorical Estimates
|
||||
|
||||
These fields are structurally important, not optional metadata. They power `taskgraph decompose`, `risk-path`, `critical`, and `bottleneck` — commands that reveal structural problems in the task graph. A task missing `scope`, `risk`, `impact`, or `level` is a red flag indicating incomplete decomposition. See the cost-benefit framework in taskgraph's framework docs for the reasoning.
|
||||
These fields are structurally important, not optional metadata. They power
|
||||
`taskgraph decompose`, `risk-path`, `critical`, and `bottleneck` — commands that
|
||||
reveal structural problems in the task graph. A task missing `scope`, `risk`,
|
||||
`impact`, or `level` is a red flag indicating incomplete decomposition. See the
|
||||
cost-benefit framework in taskgraph's framework docs for the reasoning.
|
||||
|
||||
| Scope | Description | Example |
|
||||
|-------|-------------|---------|
|
||||
| single | One function, one file | Add validation helper |
|
||||
| narrow | One component, few files | Implement auth middleware |
|
||||
| moderate | Feature, multiple components | Build user API endpoints |
|
||||
| broad | Multi-component feature | Implement OAuth flow |
|
||||
| system | Cross-cutting changes | Database migration |
|
||||
| Scope | Description | Example |
|
||||
| -------- | ---------------------------- | ------------------------- |
|
||||
| single | One function, one file | Add validation helper |
|
||||
| narrow | One component, few files | Implement auth middleware |
|
||||
| moderate | Feature, multiple components | Build user API endpoints |
|
||||
| broad | Multi-component feature | Implement OAuth flow |
|
||||
| system | Cross-cutting changes | Database migration |
|
||||
|
||||
| Risk | Failure Likelihood |
|
||||
|------|-------------------|
|
||||
| trivial | Nearly impossible to fail |
|
||||
| low | Standard implementation |
|
||||
| medium | Some uncertainty |
|
||||
| high | Significant unknowns |
|
||||
| critical | High chance of failure |
|
||||
| Risk | Failure Likelihood |
|
||||
| -------- | ------------------------- |
|
||||
| trivial | Nearly impossible to fail |
|
||||
| low | Standard implementation |
|
||||
| medium | Some uncertainty |
|
||||
| high | Significant unknowns |
|
||||
| critical | High chance of failure |
|
||||
|
||||
### Task Lifecycle
|
||||
|
||||
**Status values**: `pending` → `in-progress` → `completed` | `blocked` | `failed`
|
||||
**Status values**: `pending` → `in-progress` → `completed` | `blocked` |
|
||||
`failed`
|
||||
|
||||
**On completion**, the agent:
|
||||
|
||||
1. Updates `status: completed`
|
||||
2. Fills in `## Summary` section
|
||||
3. Commits changes to worktree branch
|
||||
@@ -351,10 +405,12 @@ When a task becomes untendable:
|
||||
### Criteria
|
||||
|
||||
**Hard Criteria** (automatic):
|
||||
|
||||
- Same task fails verification 3+ times
|
||||
- Task attempts exceed 5+ total
|
||||
|
||||
**Soft Criteria** (agent judgment):
|
||||
|
||||
- Ambiguous architecture
|
||||
- Missing dependencies
|
||||
- External library incompatibility
|
||||
@@ -371,18 +427,20 @@ When a task becomes untendable:
|
||||
|
||||
Use graph analysis to determine where reviews should happen:
|
||||
|
||||
| Analysis | Injection Point |
|
||||
|----------|-----------------|
|
||||
| Parallel groups | Review before groups merge |
|
||||
| Bottleneck tasks | Review before critical path |
|
||||
| High-risk tasks | Review before proceeding |
|
||||
| Critical path | Review before critical tasks |
|
||||
| Analysis | Injection Point |
|
||||
| ---------------- | ---------------------------- |
|
||||
| Parallel groups | Review before groups merge |
|
||||
| Bottleneck tasks | Review before critical path |
|
||||
| High-risk tasks | Review before proceeding |
|
||||
| Critical path | Review before critical tasks |
|
||||
|
||||
## Coordinator Implementation
|
||||
|
||||
### Current (open-coordinator plugin)
|
||||
|
||||
The Coordinator uses the `worktree` tool from the open-coordinator opencode plugin. It's a single tool with `{action, args}` dispatch — no separate enable/toggle steps. Role is auto-detected from session state.
|
||||
The Coordinator uses the `worktree` tool from the open-coordinator opencode
|
||||
plugin. It's a single tool with `{action, args}` dispatch — no separate
|
||||
enable/toggle steps. Role is auto-detected from session state.
|
||||
|
||||
```
|
||||
1. Identify parallel work
|
||||
@@ -413,11 +471,13 @@ The Coordinator uses the `worktree` tool from the open-coordinator opencode plug
|
||||
worktree({action: "cleanup", args: {action: "remove", pathOrBranch: "feat/auth-setup"}})
|
||||
```
|
||||
|
||||
The plugin also provides SSE-based anomaly detection (model degradation, high error count, session stall) with automatic notifications to the coordinator.
|
||||
The plugin also provides SSE-based anomaly detection (model degradation, high
|
||||
error count, session stall) with automatic notifications to the coordinator.
|
||||
|
||||
### Implementation Agent Operations
|
||||
|
||||
Spawned sessions (implementation specialists, code reviewers, POC specialists) get a limited worktree interface:
|
||||
Spawned sessions (implementation specialists, code reviewers, POC specialists)
|
||||
get a limited worktree interface:
|
||||
|
||||
```text
|
||||
worktree({action: "current"}) → Show worktree mapping
|
||||
@@ -425,17 +485,24 @@ worktree({action: "notify", args: {message: "...", level: "info|blocking"}})
|
||||
worktree({action: "status"}) → Show worktree git status
|
||||
```
|
||||
|
||||
The plugin auto-injects `workdir` for bash commands when a session is mapped to a worktree.
|
||||
The plugin auto-injects `workdir` for bash commands when a session is mapped to
|
||||
a worktree.
|
||||
|
||||
### Context & Memory (with @alkdev/open-memory)
|
||||
|
||||
When the open-memory plugin is available alongside open-coordinator, the coordinator gains:
|
||||
- `memory({tool: "children", args: {sessionId: "..."}})` — view sub-agent sessions spawned from the coordinator
|
||||
- `memory({tool: "messages", args: {sessionId: "..."}})` — read a spawned session's conversation for debugging
|
||||
- `memory({tool: "context"})` — check context window usage before long monitoring sessions
|
||||
When the open-memory plugin is available alongside open-coordinator, the
|
||||
coordinator gains:
|
||||
|
||||
- `memory({tool: "children", args: {sessionId: "..."}})` — view sub-agent
|
||||
sessions spawned from the coordinator
|
||||
- `memory({tool: "messages", args: {sessionId: "..."}})` — read a spawned
|
||||
session's conversation for debugging
|
||||
- `memory({tool: "context"})` — check context window usage before long
|
||||
monitoring sessions
|
||||
- `memory_compact()` — proactively compact at natural breakpoints
|
||||
|
||||
Implementation agents can also use `memory({tool: "context"})` and `memory_compact()` to manage their context during long tasks.
|
||||
Implementation agents can also use `memory({tool: "context"})` and
|
||||
`memory_compact()` to manage their context during long tasks.
|
||||
|
||||
### Future (Hub Operations)
|
||||
|
||||
@@ -455,7 +522,9 @@ Once the hub is operational, coordination uses native operations:
|
||||
hub.call("coord.abort", { sessionId })
|
||||
```
|
||||
|
||||
State moves from in-process tracking to Postgres `mappings` table. The open-coordinator plugin becomes unnecessary — the hub provides the same capabilities as server-side operations accessible from any environment.
|
||||
State moves from in-process tracking to Postgres `mappings` table. The
|
||||
open-coordinator plugin becomes unnecessary — the hub provides the same
|
||||
capabilities as server-side operations accessible from any environment.
|
||||
|
||||
## Document Structure
|
||||
|
||||
@@ -523,4 +592,4 @@ This document should evolve with the project:
|
||||
1. Refine roles based on actual usage
|
||||
2. Adjust task templates based on what works
|
||||
3. Document coordinator patterns as they emerge
|
||||
4. Capture learnings in after-action reviews
|
||||
4. Capture learnings in after-action reviews
|
||||
|
||||
Reference in New Issue
Block a user