Skip to content

Commit 92731e2

Browse files
TabishBTabishB
authored
refactor: split skill templates into workflow modules (#698)
* refactor: split skill templates into workflow modules * fix: align template index exports and parity docs * fix: add standard metadata to feedback skill template * fix: add ff command guardrail for context and rules * spec: add unified template generation pipeline proposal
1 parent c574e79 commit 92731e2

File tree

20 files changed

+3964
-3497
lines changed

20 files changed

+3964
-3497
lines changed

‎openspec/changes/unify-template-generation-pipeline/.openspec.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
schema: spec-driven
2+
created: 2026-02-16

‎openspec/changes/unify-template-generation-pipeline/design.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
## Context
2+
3+
OpenSpec currently has strong building blocks (workflow templates, command adapters, generation helpers), but orchestration concerns are distributed:
4+
5+
- Workflow definitions and projection lists are maintained separately
6+
- Tool support is represented in multiple places with partial overlap
7+
- Transforms can happen at template rendering time and inside individual adapters
8+
- `init`/`update`/legacy-upgrade each run similar write pipelines with slight differences
9+
10+
The design goal is to preserve current behavior while making extension points explicit and deterministic.
11+
12+
## Goals / Non-Goals
13+
14+
**Goals:**
15+
- Define one canonical source for workflow content and metadata
16+
- Make tool/agent-specific behavior explicit and centrally discoverable
17+
- Keep command adapters as the formatting boundary for tool syntax differences
18+
- Consolidate artifact generation/write orchestration into one reusable engine
19+
- Improve correctness with enforceable validation and parity tests
20+
21+
**Non-Goals:**
22+
- Redesigning command semantics or workflow instruction content
23+
- Changing user-facing CLI command names/flags in this proposal
24+
- Merging unrelated legacy cleanup behavior beyond artifact generation reuse
25+
26+
## Decisions
27+
28+
### 1. Canonical `WorkflowManifest`
29+
30+
**Decision**: Represent each workflow once in a manifest entry containing canonical skill and command definitions plus metadata defaults.
31+
32+
Suggested shape:
33+
34+
```ts
35+
interface WorkflowManifestEntry {
36+
workflowId: string; // e.g. 'explore', 'ff', 'onboard'
37+
skillDirName: string; // e.g. 'openspec-explore'
38+
skill: SkillTemplate;
39+
command?: CommandTemplate;
40+
commandId?: string;
41+
tags: string[];
42+
compatibility: string;
43+
}
44+
```
45+
46+
**Rationale**:
47+
- Eliminates drift between multiple hand-maintained arrays
48+
- Makes workflow completeness testable in one place
49+
- Keeps split workflow modules while centralizing registration
50+
51+
### 2. `ToolProfileRegistry` for capability wiring
52+
53+
**Decision**: Add a tool profile layer that maps tool IDs to generation capabilities and behavior.
54+
55+
Suggested shape:
56+
57+
```ts
58+
interface ToolProfile {
59+
toolId: string;
60+
skillsDir?: string;
61+
commandAdapterId?: string;
62+
transforms: string[];
63+
}
64+
```
65+
66+
**Rationale**:
67+
- Prevents capability drift between `AI_TOOLS`, adapter registry, and detection logic
68+
- Allows intentional "skills-only" tools without implicit special casing
69+
- Provides one place to answer "what does this tool support?"
70+
71+
### 3. First-class transform pipeline
72+
73+
**Decision**: Model transforms as ordered plugins with scope + phase + applicability.
74+
75+
Suggested shape:
76+
77+
```ts
78+
interface ArtifactTransform {
79+
id: string;
80+
scope: 'skill' | 'command' | 'both';
81+
phase: 'preAdapter' | 'postAdapter';
82+
priority: number;
83+
applies(ctx: GenerationContext): boolean;
84+
transform(content: string, ctx: GenerationContext): string;
85+
}
86+
```
87+
88+
Execution order:
89+
1. Render canonical content from manifest
90+
2. Apply matching `preAdapter` transforms
91+
3. For commands, run adapter formatting
92+
4. Apply matching `postAdapter` transforms
93+
5. Validate and write
94+
95+
**Rationale**:
96+
- Keeps adapters focused on tool formatting, not scattered behavioral rewrites
97+
- Makes agent-specific modifications explicit and testable
98+
- Replaces ad-hoc transform calls in `init`/`update`
99+
100+
### 4. Shared `ArtifactSyncEngine`
101+
102+
**Decision**: Introduce a single orchestration engine used by all generation entry points.
103+
104+
Responsibilities:
105+
- Build generation plan from `(workflows × selected tools × artifact kinds)`
106+
- Run render/transform/adapter pipeline
107+
- Validate outputs
108+
- Write files and return result summary
109+
110+
**Rationale**:
111+
- Removes duplicated loops and divergent behavior across init/update paths
112+
- Enables dry-run and future preview features without re-implementing logic
113+
- Improves reliability of updates and legacy migrations
114+
115+
### 5. Validation + parity guardrails
116+
117+
**Decision**: Add strict checks in tests (and optional runtime assertions in dev builds) for:
118+
119+
- Required skill metadata fields (`license`, `compatibility`, `metadata`) present for all manifest entries
120+
- Projection consistency (skills, commands, detection names derived from manifest)
121+
- Tool profile consistency (adapter existence, expected capabilities)
122+
- Golden/parity output for key workflows/tools
123+
124+
**Rationale**:
125+
- Converts prior review issues into enforced invariants
126+
- Preserves output fidelity while enabling internal refactors
127+
- Makes regressions obvious during CI
128+
129+
## Risks / Trade-offs
130+
131+
**Risk: Migration complexity**
132+
A broad refactor can destabilize generation paths.
133+
→ Mitigation: introduce in phases with parity tests before cutover.
134+
135+
**Risk: Over-abstraction**
136+
Too many layers can obscure simple flows.
137+
→ Mitigation: keep interfaces minimal and colocate registries with generation code.
138+
139+
**Trade-off: More upfront structure**
140+
Adding manifest/profile/transform registries increases conceptual surface area.
141+
→ Accepted: this cost is offset by reduced drift and easier extension.
142+
143+
## Implementation Approach
144+
145+
1. Build manifest + profile + transform types and registries behind current public API
146+
2. Rewire `getSkillTemplates`/`getCommandContents` to derive from manifest
147+
3. Introduce `ArtifactSyncEngine` and switch `init` to use it with parity checks
148+
4. Switch `update` and legacy upgrade flows to same engine
149+
5. Remove duplicate/hardcoded lists after parity is green

‎openspec/changes/unify-template-generation-pipeline/proposal.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
## Why
2+
3+
The recent split of `skill-templates.ts` into workflow modules improved readability, but the generation pipeline is still fragmented across multiple layers:
4+
5+
- Workflow definitions are split from projection logic (`getSkillTemplates`, `getCommandTemplates`, `getCommandContents`)
6+
- Tool capability and compatibility are spread across `AI_TOOLS`, `CommandAdapterRegistry`, and hardcoded lists like `SKILL_NAMES`
7+
- Agent/tool-specific transformations (for example OpenCode command reference rewrites) are applied in different places (`init`, `update`, and adapter code)
8+
- Artifact writing logic is duplicated across `init`, `update`, and legacy-upgrade flow
9+
10+
This fragmentation creates drift risk (missing exports, missing metadata parity, mismatched counts/support) and makes future workflow/tool additions slower and less predictable.
11+
12+
## What Changes
13+
14+
- Introduce a canonical `WorkflowManifest` as the single source of truth for all workflow artifacts
15+
- Introduce a `ToolProfileRegistry` to centralize tool capabilities (skills path, command adapter, transforms)
16+
- Introduce a first-class transform pipeline with explicit phases (`preAdapter`, `postAdapter`) and scopes (`skill`, `command`, `both`)
17+
- Introduce a shared `ArtifactSyncEngine` used by `init`, `update`, and legacy upgrade paths
18+
- Add strict validation and test guardrails to preserve fidelity during migration and future changes
19+
20+
## Capabilities
21+
22+
### New Capabilities
23+
24+
- `template-artifact-pipeline`: Unified workflow manifest, tool profile registry, transform pipeline, and sync engine for skill/command generation
25+
26+
### Modified Capabilities
27+
28+
- `command-generation`: Extended to support ordered transform phases around adapter rendering
29+
- `cli-init`: Uses shared artifact sync orchestration instead of bespoke loops
30+
- `cli-update`: Uses shared artifact sync orchestration instead of bespoke loops
31+
32+
## Impact
33+
34+
- **Primary refactor area**:
35+
- `src/core/templates/*`
36+
- `src/core/shared/skill-generation.ts`
37+
- `src/core/command-generation/*`
38+
- `src/core/init.ts`
39+
- `src/core/update.ts`
40+
- `src/core/shared/tool-detection.ts`
41+
- **Testing additions**:
42+
- Manifest completeness tests (workflows, required metadata, projection parity)
43+
- Transform ordering and applicability tests
44+
- End-to-end parity tests for generated skill/command outputs across tools
45+
- **User-facing behavior**:
46+
- No new CLI surface area required
47+
- Existing generated artifacts remain behaviorally equivalent unless explicitly changed in future deltas

‎openspec/changes/unify-template-generation-pipeline/specs/template-artifact-pipeline/spec.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# template-artifact-pipeline Specification
2+
3+
## Purpose
4+
5+
Define a unified architecture for workflow template generation that centralizes workflow definitions, tool capability wiring, transform execution, and artifact synchronization while preserving output fidelity.
6+
7+
## ADDED Requirements
8+
9+
### Requirement: Canonical Workflow Manifest
10+
11+
The system SHALL define a canonical workflow manifest as the single source of truth for generated skill and command artifacts.
12+
13+
#### Scenario: Register workflow once
14+
15+
- **WHEN** a workflow (for example `explore`, `ff`, or `onboard`) is added or modified
16+
- **THEN** its canonical definition SHALL be registered once in the workflow manifest
17+
- **AND** skill/command projections SHALL be derived from that manifest
18+
- **AND** duplicate hand-maintained lists SHALL NOT be required
19+
20+
#### Scenario: Required skill metadata
21+
22+
- **WHEN** defining a workflow skill entry in the manifest
23+
- **THEN** it SHALL include required metadata fields (`license`, `compatibility`, and `metadata`)
24+
- **AND** generation SHALL use those values or explicit defaults in a consistent way for all workflows
25+
26+
### Requirement: Tool Profile Registry
27+
28+
The system SHALL define a tool profile registry that captures generation capabilities per tool.
29+
30+
#### Scenario: Resolve tool capabilities
31+
32+
- **WHEN** generating artifacts for a selected tool
33+
- **THEN** the system SHALL resolve a tool profile that declares skill path capability, command adapter linkage, and transform set
34+
- **AND** tools with skills support but no command adapter SHALL be handled explicitly without implicit fallback behavior
35+
36+
#### Scenario: Capability consistency validation
37+
38+
- **WHEN** running validation checks
39+
- **THEN** the system SHALL detect mismatches between configured tools, profile definitions, and registered adapters
40+
- **AND** fail with actionable errors in development/CI
41+
42+
### Requirement: Ordered Transform Pipeline
43+
44+
The system SHALL support ordered artifact transforms with explicit scope and phase semantics.
45+
46+
#### Scenario: Execute pre-adapter and post-adapter transforms
47+
48+
- **WHEN** generating an artifact
49+
- **THEN** matching transforms SHALL execute in deterministic order based on phase and priority
50+
- **AND** `preAdapter` transforms SHALL run before command adapter formatting
51+
- **AND** `postAdapter` transforms SHALL run after adapter formatting
52+
53+
#### Scenario: Apply tool-specific rewrites declaratively
54+
55+
- **WHEN** a tool requires instruction rewrites (for example command reference syntax changes)
56+
- **THEN** those rewrites SHALL be implemented as registered transforms with explicit applicability predicates
57+
- **AND** generation entry points SHALL NOT implement ad-hoc rewrite logic
58+
59+
### Requirement: Shared Artifact Sync Engine
60+
61+
The system SHALL provide a shared artifact sync engine used by all generation entry points.
62+
63+
#### Scenario: Init and update use same engine
64+
65+
- **WHEN** `openspec init` or `openspec update` writes skills/commands
66+
- **THEN** both flows SHALL use the same orchestration engine for planning, rendering, validating, and writing artifacts
67+
- **AND** behavior differences SHALL be configuration-driven rather than separate duplicated loops
68+
69+
#### Scenario: Legacy upgrade path reuses engine
70+
71+
- **WHEN** legacy cleanup triggers artifact regeneration
72+
- **THEN** the regeneration path SHALL use the same shared engine
73+
- **AND** generated outputs SHALL follow the same transform and validation rules
74+
75+
### Requirement: Fidelity Guardrails
76+
77+
The system SHALL enforce guardrails that prevent output drift during refactors.
78+
79+
#### Scenario: Projection parity checks
80+
81+
- **WHEN** CI runs template generation tests
82+
- **THEN** it SHALL verify manifest-derived projections remain consistent (workflows, command IDs, skill directories)
83+
- **AND** detect missing exports or missing workflow registration
84+
85+
#### Scenario: Output parity checks
86+
87+
- **WHEN** running parity tests for representative workflow/tool combinations
88+
- **THEN** generated artifacts SHALL remain behaviorally equivalent to approved baselines unless intentionally changed
89+
- **AND** intentional changes SHALL be captured in explicit spec/proposal updates

‎openspec/changes/unify-template-generation-pipeline/tasks.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
## 1. Manifest Foundation
2+
3+
- [ ] 1.1 Create canonical workflow manifest registry under `src/core/templates/`
4+
- [ ] 1.2 Define shared manifest types for workflow IDs, skill metadata, and optional command descriptors
5+
- [ ] 1.3 Migrate existing workflow registration (`getSkillTemplates`, `getCommandTemplates`, `getCommandContents`) to derive from the manifest
6+
- [ ] 1.4 Preserve existing external exports/API compatibility for `src/core/templates/skill-templates.ts`
7+
8+
## 2. Tool Profile Layer
9+
10+
- [ ] 2.1 Add `ToolProfile` types and `ToolProfileRegistry`
11+
- [ ] 2.2 Map all currently supported tools to explicit profile entries
12+
- [ ] 2.3 Wire profile lookups to command adapter resolution and skills path resolution
13+
- [ ] 2.4 Replace hardcoded detection arrays (for example `SKILL_NAMES`) with manifest-derived values
14+
15+
## 3. Transform Pipeline
16+
17+
- [ ] 3.1 Introduce transform interfaces (`scope`, `phase`, `priority`, `applies`, `transform`)
18+
- [ ] 3.2 Implement transform runner with deterministic ordering
19+
- [ ] 3.3 Migrate OpenCode command reference rewrite to transform pipeline
20+
- [ ] 3.4 Remove ad-hoc transform invocation from `init` and `update`
21+
22+
## 4. Artifact Sync Engine
23+
24+
- [ ] 4.1 Create shared artifact sync engine for generation planning + rendering + writing
25+
- [ ] 4.2 Integrate engine into `init` flow
26+
- [ ] 4.3 Integrate engine into `update` flow
27+
- [ ] 4.4 Integrate engine into legacy-upgrade artifact generation path
28+
29+
## 5. Validation and Tests
30+
31+
- [ ] 5.1 Add manifest completeness tests (metadata required fields, command IDs, dir names)
32+
- [ ] 5.2 Add tool-profile consistency tests (skillsDir support and adapter/profile alignment)
33+
- [ ] 5.3 Add transform applicability/order tests
34+
- [ ] 5.4 Expand parity tests for representative workflow/tool matrix
35+
- [ ] 5.5 Run full test suite and verify generated artifacts remain stable
36+
37+
## 6. Cleanup and Documentation
38+
39+
- [ ] 6.1 Remove superseded helper code and duplicate write loops after cutover
40+
- [ ] 6.2 Update internal developer docs for template generation architecture
41+
- [ ] 6.3 Document migration guardrails for future workflow/tool additions

‎src/core/templates/index.ts‎

Lines changed: 2 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -5,24 +5,5 @@
55
* have been removed. The skill-based workflow uses skill-templates.ts directly.
66
*/
77

8-
// Re-export skill templates for convenience
9-
export {
10-
getExploreSkillTemplate,
11-
getNewChangeSkillTemplate,
12-
getContinueChangeSkillTemplate,
13-
getApplyChangeSkillTemplate,
14-
getFfChangeSkillTemplate,
15-
getSyncSpecsSkillTemplate,
16-
getArchiveChangeSkillTemplate,
17-
getBulkArchiveChangeSkillTemplate,
18-
getVerifyChangeSkillTemplate,
19-
getOpsxExploreCommandTemplate,
20-
getOpsxNewCommandTemplate,
21-
getOpsxContinueCommandTemplate,
22-
getOpsxApplyCommandTemplate,
23-
getOpsxFfCommandTemplate,
24-
getOpsxSyncCommandTemplate,
25-
getOpsxArchiveCommandTemplate,
26-
getOpsxBulkArchiveCommandTemplate,
27-
getOpsxVerifyCommandTemplate,
28-
} from './skill-templates.js';
8+
// Re-export all skill templates and related types through the compatibility facade.
9+
export * from './skill-templates.js';

0 commit comments

Comments
 (0)