Skip to content

feat: add workflow profiles with trellis co-creation specs#133

Open
RogerNavelsaker wants to merge 7 commits intojayminwest:mainfrom
RogerNavelsaker:rn/workflow-profiles-trellis-main
Open

feat: add workflow profiles with trellis co-creation specs#133
RogerNavelsaker wants to merge 7 commits intojayminwest:mainfrom
RogerNavelsaker:rn/workflow-profiles-trellis-main

Conversation

@RogerNavelsaker
Copy link
Copy Markdown
Contributor

Summary

  • add first-class workflow aliases for delivery and co-creation across coordinator startup, ov workflow start, ov sling, and ov spec write
  • use Trellis for co-creation spec output under .trellis/specs/<task-id>.yaml while keeping delivery on .overstory/specs/
  • make ov spec write a Trellis-aware bootstrap surface with --title, --seed, repeated --reference, --constraint, and --acceptance
  • protect existing Trellis specs from overwrite by default and require --force for replacement
  • keep plan creation in Trellis and leave deeper ongoing authoring there
  • fall back to emitted workflow prompt files when Canopy is unavailable so workflow-mode prompts still apply

Closes #106.

Testing

  • bun test src/workflow.test.ts src/commands/spec.test.ts src/commands/workflow.test.ts src/commands/coordinator.test.ts src/commands/completions.test.ts
  • bun x tsc --noEmit
  • bunx @biomejs/biome check README.md src/workflow.ts src/workflow.test.ts src/commands/spec.ts src/commands/spec.test.ts src/commands/workflow.ts src/commands/workflow.test.ts src/commands/coordinator.ts src/commands/coordinator.test.ts src/index.ts src/commands/completions.ts src/commands/completions.test.ts

Notes

  • This is the Trellis-native replacement path for feat: add first-class workflow profiles #130 after downstream dogfooding.
  • Downstream dogfooding confirmed the boundary: ov spec write --workflow co-creation is the bootstrap path, trellis spec update is the ongoing edit path, and trellis plan create remains the plan-authoring path.

@RogerNavelsaker
Copy link
Copy Markdown
Contributor Author

Three-phase workflow: Plan → Trellis → Seeds → Code

This PR establishes the entry point for co-creation mode and bootstraps Trellis specs. It surfaces a natural next layer: full workflow automation across three spaces.

The three spaces

Plan space — where the system is designed
A large markdown plan (single document, full system context) is the primary artifact. No code is written here. The value is that a plan fits in context while the resulting codebase won't — all high-level reasoning happens while global coherence is still possible.

Trellis/Seeds space — where the plan becomes executable memory
The plan is decomposed into Trellis specs and Seeds issues with an explicit dependency graph. Each unit is self-contained: it carries enough context that an agent can execute it without consulting the full plan. This is the bridge between intent and implementation.

Code space — where agents implement and verify
Agents receive specs and issue IDs. They implement, test, and close. The high-level decisions are already locked in — agents make implementation choices, not architectural ones.

What this PR introduces (the bootstrap path)

ov spec write --workflow co-creation seeds a Trellis spec. ov workflow start co-creation starts a coordinator in the right mode. That covers the transition from Trellis → Code.

What's missing to complete the loop

1. Plan space orchestration (ov plan)

There is currently no command to drive the plan creation phase. A natural surface:

ov plan refine <plan.md>
  --agents <n>       # parallel scout agents generating alternative approaches
  --rounds <n>       # synthesis iterations until convergence
  --output <out.md>  # distilled plan ready for bootstrap

Each round: N scouts read the current plan and produce suggestions in parallel → synthesizer agent collapses them into a revised plan → repeat. Convergence is detectable (output shrinks, change velocity drops). This lives entirely in plan space — no Trellis specs, no Seeds issues, no worktrees yet.

2. Batch bootstrap (ov plan bootstrap)

ov spec write is one-at-a-time. Going from a refined plan to a full Trellis + Seeds setup needs a batch path:

ov plan bootstrap <refined.md>
  --workflow co-creation     # writes .trellis/specs/*.yaml
  --emit-issues              # sd create + sd dep add from plan structure
  --dry-run

The plan document encodes the structure needed for both: sections become Trellis specs, ordering/dependencies become the Seeds graph. --seed in ov spec write records the link per spec; this step constructs the whole graph at once.

3. Spec polishing (ov spec polish)

Before any agents touch code, the spec set should be stable. A polishing loop:

ov spec polish [<task-id>...]
  --rounds <n>
  --convergence 0.75         # similarity threshold to stop
  --against <plan.md>        # cross-reference against original plan

Detects duplicates, missing context, broken dependency references. This is a distinct phase from plan refinement — the plan is frozen, the specs are being hardened.

4. Graph-aware routing for Seeds

sd ready surfaces unblocked issues but doesn't account for graph topology. The dependency graph has structure worth exploiting: some issues are bottlenecks (many dependents), some are on the critical path, some are parallelizable leaves.

Options:

  • Extend Seeds with a sd graph or sd route command that runs PageRank + betweenness centrality on the issue dep graph and returns prioritized work
  • A standalone ov route command that reads the Seeds graph and emits an ordered work list for the coordinator to dispatch
  • A new os-eco tool (grove? canopy extension?) that owns graph analysis across the dep structure

This is the routing layer that prevents agents from randomly picking equivalent-priority work when there are true critical-path bottlenecks to unblock first.

Sequencing

This PR's scope is right as-is. The items above are follow-on work, roughly in order:

  1. ov plan bootstrap (highest leverage — closes the plan → Trellis/Seeds gap)
  2. Graph routing for Seeds (changes agent dispatch quality immediately)
  3. ov plan refine (adds the parallel planning phase)
  4. ov spec polish (adds pre-code hardening)

RogerNavelsaker and others added 2 commits March 26, 2026 11:44
- Move collectValues helper from src/index.ts to src/commands/spec.ts
  (entry point should not contain utility functions)
- Remove non-existent 'trellis spec update' command reference from error message
- Skip empty YAML sections (constraints/acceptance/references) when lists are empty
- Expand validateWorkflowName error to list all accepted aliases

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add first-class workflow profiles: delivery and co-creation

1 participant