sauron-cli 1.1.3 → 1.3.0

package/OpenSpec-main/openspec/changes/simplify-skill-installation/specs/profiles/spec.md

@@ -0,0 +1,142 @@
+## Purpose
+
+Profiles SHALL define which workflows to install, enabling a streamlined core experience for new users while allowing power users to customize their workflow selection.
+
+## ADDED Requirements
+
+### Requirement: Profile definitions
+The system SHALL support two workflow profiles: `core` and `custom`.
+
+#### Scenario: Core profile contents
+- **WHEN** profile is set to `core`
+- **THEN** the profile SHALL include workflows: `propose`, `explore`, `apply`, `archive`
+
+#### Scenario: Custom profile contents
+- **WHEN** profile is set to `custom`
+- **THEN** the profile SHALL include only the workflows specified in global config `workflows` array
+
+### Requirement: Delivery is independent of profile
+The delivery setting SHALL control HOW workflows are installed (skills, commands, or both), separate from WHICH workflows are installed.
+
+#### Scenario: Delivery options
+- **WHEN** configuring delivery
+- **THEN** the system SHALL support three options: `both` (skills and commands), `skills` (skill files only), `commands` (command files only)
+
+#### Scenario: Both delivery
+- **WHEN** delivery is set to `both`
+- **THEN** the system SHALL install both skill files and command files for each workflow
+
+#### Scenario: Skills-only delivery
+- **WHEN** delivery is set to `skills`
+- **THEN** the system SHALL install only skill files for each workflow
+- **THEN** the system SHALL NOT install command files
+
+#### Scenario: Commands-only delivery
+- **WHEN** delivery is set to `commands`
+- **THEN** the system SHALL install only command files for each workflow
+- **THEN** the system SHALL NOT install skill files
+
+#### Scenario: Core profile with custom delivery
+- **WHEN** profile is set to `core`
+- **AND** delivery is set to `skills`
+- **THEN** the system SHALL install core workflows as skills only (no commands)
+
+#### Scenario: Delivery defaults
+- **WHEN** delivery is not set in global config
+- **THEN** the system SHALL default to `both`
+
+### Requirement: Profile configuration via interactive picker
+The system SHALL provide an interactive picker for configuring profiles.
+
+#### Scenario: Interactive profile configuration
+- **WHEN** user runs `openspec config profile`
+- **THEN** the system SHALL display an interactive picker with:
+  - Delivery selection: `skills`, `commands`, `both`
+  - Workflow toggles for all available workflows
+- **THEN** the system SHALL pre-select current config values
+- **THEN** on confirmation, the system SHALL update global config
+- **THEN** the system SHALL set profile to `custom` if selected workflows differ from core defaults
+- **THEN** the system SHALL set profile to `core` if selected workflows match core defaults exactly (propose, explore, apply, archive), regardless of delivery setting
+- **THEN** the system SHALL NOT modify any project files
+- **THEN** the system SHALL display: "Config updated. Run `openspec update` in your projects to apply."
+
+#### Scenario: Core preset shortcut
+- **WHEN** user runs `openspec config profile core`
+- **THEN** the system SHALL set profile to `core`
+- **THEN** the system SHALL set workflows to `['propose', 'explore', 'apply', 'archive']`
+- **THEN** the system SHALL NOT change the delivery setting (preserves user preference)
+- **THEN** the system SHALL NOT modify any project files
+- **THEN** the system SHALL display: "Config updated. Run `openspec update` in your projects to apply."
+- **THEN** the new profile takes effect on the next `openspec init` or `openspec update` run
+
+#### Scenario: Config profile run inside a project
+- **WHEN** user runs `openspec config profile` inside an OpenSpec project directory
+- **THEN** after updating global config, the system SHALL prompt: "Apply to this project now? (y/n)"
+- **WHEN** user confirms
+- **THEN** the system SHALL run `openspec update` automatically
+- **THEN** the system SHALL still display: "Run `openspec update` in your other projects to apply."
+
+#### Scenario: Config profile - user declines apply
+- **WHEN** user runs `openspec config profile` inside an OpenSpec project directory
+- **AND** user declines the "Apply to this project now?" prompt
+- **THEN** the system SHALL display: "Config updated. Run `openspec update` in your projects to apply."
+- **THEN** the system SHALL exit successfully without modifying project files
+
+#### Scenario: Config profile non-interactive
+- **WHEN** user runs `openspec config profile` non-interactively (e.g., in CI, no TTY)
+- **THEN** the system SHALL display an error: "Interactive mode required. Use `openspec config profile core` or set config via environment/flags."
+- **THEN** the system SHALL exit with code 1
+
+### Requirement: Profile settings stored in global config
+Profile and delivery settings SHALL be stored in the existing global config file (`~/.config/openspec/config.json`) alongside telemetry and feature flags.
+
+#### Scenario: Config schema
+- **WHEN** reading profile configuration
+- **THEN** the config SHALL contain `profile` (core|custom), `delivery` (both|skills|commands), and optionally `workflows` (array of workflow names)
+
+#### Scenario: Schema evolution
+- **WHEN** loading config without profile/delivery fields
+- **THEN** the system SHALL use defaults (profile=core, delivery=both)
+- **AND** existing config fields (telemetry, featureFlags) SHALL be preserved
+
+#### Scenario: Config list displays profile settings
+- **WHEN** user runs `openspec config list`
+- **THEN** the system SHALL display profile, delivery, and workflows settings
+- **AND** SHALL indicate which values are defaults vs explicitly set
+
+### Requirement: Config is global, projects are explicit
+Config changes SHALL NOT automatically propagate to projects.
+
+#### Scenario: Config update does not modify projects
+- **WHEN** user updates config via `openspec config profile`
+- **THEN** the system SHALL only update global config (`~/.config/openspec/config.json`)
+- **THEN** the system SHALL NOT modify any project skill/command files
+- **THEN** existing projects retain their current workflow files until user runs `openspec update`
+
+### Requirement: Config changes applied via update command
+The existing `openspec update` command SHALL apply the current global config to a project. See `specs/cli-update/spec.md` for detailed update behavior.
+
+#### Scenario: Config changes require explicit project sync
+- **WHEN** user updates profile or delivery via `openspec config profile`
+- **THEN** the global config SHALL be updated immediately
+- **AND** project files SHALL remain unchanged until `openspec update` is run for that project
+
+### Requirement: Profile defaults
+The system SHALL use `core` as the default profile for new users, while preserving existing users' workflows via migration.
+
+#### Scenario: No global config exists (new user)
+- **WHEN** global config file does not exist
+- **AND** no existing workflows are installed in the project
+- **THEN** the system SHALL behave as if profile is `core`
+
+#### Scenario: Global config exists but profile field absent (new user)
+- **WHEN** global config file exists but does not contain a `profile` field
+- **AND** no existing workflows are installed in the project
+- **THEN** the system SHALL behave as if profile is `core`
+
+#### Scenario: Profile field absent with existing workflows (existing user migration)
+- **WHEN** global config does not contain a `profile` field
+- **AND** the `update` command detects existing workflow files in the project
+- **THEN** the system SHALL perform one-time migration (see `specs/cli-update/spec.md` for details)
+- **THEN** the system SHALL set profile to `custom` with the detected workflows
+- **THEN** the system SHALL NOT add or remove any workflow files during migration

package/OpenSpec-main/openspec/changes/simplify-skill-installation/specs/propose-workflow/spec.md

@@ -0,0 +1,42 @@
+## Purpose
+
+The propose workflow SHALL combine change creation and artifact generation into a single command, reducing friction for new users while teaching them the OpenSpec workflow through embedded guidance.
+
+## ADDED Requirements
+
+### Requirement: Propose workflow creation
+The system SHALL provide a `propose` workflow that creates a change and generates all artifacts in one step.
+
+#### Scenario: Basic propose invocation
+- **WHEN** user invokes `/opsx:propose "add user authentication"`
+- **THEN** the system SHALL create a change directory with kebab-case name
+- **THEN** the system SHALL create `.openspec.yaml` in the change directory (via `openspec new change`)
+- **THEN** the system SHALL generate all artifacts needed for implementation: proposal.md, design.md, specs/, tasks.md
+
+#### Scenario: Propose with existing change name
+- **WHEN** user invokes `/opsx:propose` with a name that already exists
+- **THEN** the system SHALL ask if user wants to continue existing change or create new
+- **THEN** if "continue": the system SHALL resume artifact generation from last completed state
+- **THEN** if "create new": the system SHALL prompt for a new name
+- **THEN** in non-interactive mode: the system SHALL fail with error suggesting to use a different name
+
+### Requirement: Propose workflow onboarding UX
+The `propose` workflow SHALL include explanatory output to help new users understand the process.
+
+#### Scenario: First-time user guidance
+- **WHEN** user invokes `/opsx:propose`
+- **THEN** the system SHALL explain what artifacts will be created (proposal.md, design.md, specs/, tasks.md)
+- **THEN** the system SHALL indicate next step (`/opsx:apply` to implement)
+
+#### Scenario: Artifact creation progress
+- **WHEN** the system creates each artifact
+- **THEN** the system SHALL show progress (e.g., "✓ Created proposal.md")
+
+### Requirement: Propose workflow combines new and ff
+The `propose` workflow SHALL perform the same operations as running `new` followed by `ff`.
+
+#### Scenario: Equivalent to new + ff
+- **WHEN** user invokes `/opsx:propose "feature name"`
+- **THEN** the result SHALL be functionally equivalent to invoking `/opsx:new "feature-name"` followed by `/opsx:ff feature-name`
+- **THEN** the same directory structure and artifacts SHALL be created
+- **THEN** console output MAY differ (propose includes onboarding explanations)

package/OpenSpec-main/openspec/changes/simplify-skill-installation/tasks.md

@@ -0,0 +1,132 @@
+## 1. Global Config Extension
+
+- [x] 1.1 Extend `src/core/global-config.ts` schema with `profile`, `delivery`, and `workflows` fields
+- [x] 1.2 Add TypeScript types for profile (`core` | `custom`), delivery (`both` | `skills` | `commands`), and workflows (string array)
+- [x] 1.3 Update `GlobalConfig` interface and defaults (profile=`core`, delivery=`both`)
+- [x] 1.4 Update existing `readGlobalConfig()` to handle missing new fields with defaults
+- [x] 1.5 Add tests for schema evolution (existing config without new fields)
+
+## 2. Profile System
+
+- [x] 2.1 Create `src/core/profiles.ts` with profile definitions (core, custom)
+- [x] 2.2 Define `CORE_WORKFLOWS` constant: `['propose', 'explore', 'apply', 'archive']`
+- [x] 2.3 Define `ALL_WORKFLOWS` constant with all 11 workflows
+- [x] 2.4 Add `COMMAND_IDS` constant to `src/core/shared/tool-detection.ts` (parallel to existing SKILL_NAMES)
+- [x] 2.5 Implement `getProfileWorkflows(profile, customWorkflows?)` resolver function
+- [x] 2.6 Add tests for profile resolution
+
+## 3. Config Profile Command (Interactive Picker)
+
+- [x] 3.1 Add `config profile` subcommand to `src/commands/config.ts`
+- [x] 3.2 Implement interactive picker UI with delivery selection (skills/commands/both)
+- [x] 3.3 Implement interactive picker UI with workflow toggles
+- [x] 3.4 Pre-select current config values in picker
+- [x] 3.5 Update global config on confirmation (config-only, no file regeneration)
+- [x] 3.6 Display post-update message: "Config updated. Run `openspec update` in your projects to apply."
+- [x] 3.7 Detect if running inside an OpenSpec project and offer to run update automatically
+- [x] 3.8 Implement `config profile core` preset shortcut (preserves delivery setting)
+- [x] 3.9 Handle non-interactive mode: error with helpful message
+- [x] 3.10 Update `openspec config list` to display profile, delivery, and workflows settings (indicate defaults vs explicit)
+- [x] 3.11 Add tests for config profile command and config list output
+
+## 4. Available Tools Detection
+
+- [x] 4.1 Create `src/core/available-tools.ts` (separate from existing `tool-detection.ts`)
+- [x] 4.2 Implement `getAvailableTools(projectPath)` that scans for AI tool directories (`.claude/`, `.cursor/`, etc.)
+- [x] 4.3 Use `AI_TOOLS` config to map directory names to tool IDs
+- [x] 4.4 Add tests for available tools detection including cross-platform paths
+
+## 5. Propose Workflow Template
+
+- [x] 5.1 Create `src/core/templates/workflows/propose.ts`
+- [x] 5.2 Implement skill template that combines new + ff behavior
+- [x] 5.3 Ensure propose creates `.openspec.yaml` via `openspec new change` before generating artifacts
+- [x] 5.4 Add onboarding-style explanatory output to template
+- [x] 5.5 Implement command template for propose
+- [x] 5.6 Export templates from `src/core/templates/skill-templates.ts`
+- [x] 5.7 Add `openspec-propose` to `SKILL_NAMES` in `src/core/shared/tool-detection.ts`
+- [x] 5.8 Add `propose` to command templates in `src/core/shared/skill-generation.ts`
+- [x] 5.9 Add `propose` to `COMMAND_IDS` in `src/core/shared/tool-detection.ts`
+- [x] 5.10 Add tests for propose template (creates change, generates artifacts, equivalent to new + ff)
+
+## 6. Conditional Skill/Command Generation
+
+- [x] 6.1 Update `getSkillTemplates()` to accept profile filter parameter
+- [x] 6.2 Update `getCommandTemplates()` to accept profile filter parameter
+- [x] 6.3 Update `generateSkillsAndCommands()` in init.ts to respect delivery setting
+- [x] 6.4 Add logic to skip skill generation when delivery is 'commands'
+- [x] 6.5 Add logic to skip command generation when delivery is 'skills'
+- [x] 6.6 Add tests for conditional generation
+
+## 7. Init Flow Updates
+
+- [x] 7.1 Update init to call `getAvailableTools()` first
+- [x] 7.2 Update init to read global config for profile/delivery defaults
+- [x] 7.3 Add migration check to init: call shared `migrateIfNeeded()` before profile resolution
+- [x] 7.4 Change tool selection to show pre-selected detected tools
+- [x] 7.5 Apply configured profile directly in init (no profile confirmation prompt)
+- [x] 7.6 Update success message to show `/opsx:propose` prompt (only if propose is in the active profile)
+- [x] 7.7 Add `--profile` flag to override global config
+- [x] 7.8 Update non-interactive mode to use defaults without prompting
+- [x] 7.9 Add tests for init flow with various scenarios (including migration on re-init and custom profile behavior)
+
+## 8. Update Command (Profile Support + Migration)
+
+- [x] 8.1 Modify existing `src/commands/update.ts` to read global config for profile/delivery/workflows
+- [x] 8.2 Implement shared `scanInstalledWorkflows(projectPath, tools)` — scan tool directories, match only against `ALL_WORKFLOWS` constant, return union across tools
+- [x] 8.3 Implement shared `migrateIfNeeded(projectPath, tools)` — one-time migration logic used by both `init` and `update`
+- [x] 8.4 Display migration message: "Migrated: custom profile with N workflows" + "New in this version: /opsx:propose. Try 'openspec config profile core' for the streamlined experience."
+- [x] 8.5 Add project check: exit with error if no `openspec/` directory exists
+- [x] 8.6 Add logic to detect which workflows are in config but not installed (to add)
+- [x] 8.7 Add logic to detect which workflows are installed and need refresh (to update)
+- [x] 8.8 Respect delivery setting: generate only skills if `skills`, only commands if `commands`
+- [x] 8.9 Delete files when delivery changes: remove commands if `skills`, remove skills if `commands`
+- [x] 8.10 Generate new workflow files for missing workflows in profile
+- [x] 8.11 Display summary: "Added: X, Y" / "Updated: Z" / "Removed: N files" / "Already up to date."
+- [x] 8.12 List affected tools in output: "Tools: Claude Code, Cursor"
+- [x] 8.13 Detect new tool directories not currently configured and display hint to re-init
+- [x] 8.14 Add tests for migration scenarios (existing user, partial workflows, multiple tools, idempotent, custom skills ignored)
+- [x] 8.15 Add tests for update command with profile scenarios (including delivery changes, outside-project error, new tool detection)
+
+## 9. Tool Selection UX Fix
+
+- [x] 9.1 Update `src/prompts/searchable-multi-select.ts` keybindings
+- [x] 9.2 Change Space to toggle selection
+- [x] 9.3 Change Enter to confirm selection
+- [x] 9.4 Remove Tab-to-confirm behavior
+- [x] 9.5 Add hint text "Space to toggle, Enter to confirm"
+- [x] 9.6 Add tests for keybinding behavior
+
+## 10. Scaffolding Verification
+
+- [x] 10.1 Verify `openspec new change` creates `.openspec.yaml` with schema and created fields
+
+<!-- Note: 10.2 and 10.3 below are potential follow-up work, not core to this change -->
+<!-- - [ ] 10.2 Update ff skill to verify `.openspec.yaml` exists after `openspec new change` -->
+<!-- - [ ] 10.3 Add guardrail to skills: "Never manually create files in openspec/changes/ - use openspec new change" -->
+
+## 11. Template Next-Step Guidance
+
+- [x] 11.1 Audit all templates for hardcoded cross-workflow command references (e.g., `/opsx:propose`)
+- [x] 11.2 Replace any specific command references with generic concept-based guidance (e.g., "create a change proposal")
+- [x] 11.3 Review explore → propose transition UX (see `openspec/explorations/explore-workflow-ux.md` for open questions)
+
+## 12. Integration & Manual Testing
+
+- [x] 12.1 Run full test suite and fix any failures
+- [x] 12.2 Test on Windows (or verify CI passes on Windows)
+- [x] 12.3 Test end-to-end flow: init → propose → apply → archive
+- [x] 12.4 Update CLI help text for new commands
+- [x] 12.5 Manual: interactive init — verify detected tools are pre-selected, confirm prompt works, success message is correct
+- [x] 12.6 Manual: `openspec config profile` picker — verify delivery toggle, workflow toggles, pre-selection of current values, core preset shortcut
+- [x] 12.7 Manual: init with custom profile — verify init proceeds without profile confirmation prompt
+- [x] 12.8 Manual: delivery change via update — verify correct files are deleted/created when switching between skills/commands/both
+- [x] 12.9 Manual: migration flow — run update on a pre-existing project with no profile in config, verify migration message and resulting config
+
+## 13. Post-Implementation Hardening (Review Follow-up)
+
+- [x] 13.1 Ensure `update` treats profile/delivery drift as update-required even when templates are current
+- [x] 13.2 Ensure `update` recognizes command-only installations as configured tools
+- [x] 13.3 Ensure `init` validates `--profile` values and errors on invalid overrides
+- [x] 13.4 Ensure re-running `init` applies delivery cleanup (removes files not matching current delivery mode)
+- [x] 13.5 Add/adjust regression tests for config drift sync, command-only detection, invalid profile override, and re-init delivery cleanup

package/OpenSpec-main/openspec/changes/unify-template-generation-pipeline/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-16

package/OpenSpec-main/openspec/changes/unify-template-generation-pipeline/design.md

@@ -0,0 +1,149 @@
+## Context
+
+OpenSpec currently has strong building blocks (workflow templates, command adapters, generation helpers), but orchestration concerns are distributed:
+
+- Workflow definitions and projection lists are maintained separately
+- Tool support is represented in multiple places with partial overlap
+- Transforms can happen at template rendering time and inside individual adapters
+- `init`/`update`/legacy-upgrade each run similar write pipelines with slight differences
+
+The design goal is to preserve current behavior while making extension points explicit and deterministic.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Define one canonical source for workflow content and metadata
+- Make tool/agent-specific behavior explicit and centrally discoverable
+- Keep command adapters as the formatting boundary for tool syntax differences
+- Consolidate artifact generation/write orchestration into one reusable engine
+- Improve correctness with enforceable validation and parity tests
+
+**Non-Goals:**
+- Redesigning command semantics or workflow instruction content
+- Changing user-facing CLI command names/flags in this proposal
+- Merging unrelated legacy cleanup behavior beyond artifact generation reuse
+
+## Decisions
+
+### 1. Canonical `WorkflowManifest`
+
+**Decision**: Represent each workflow once in a manifest entry containing canonical skill and command definitions plus metadata defaults.
+
+Suggested shape:
+
+```ts
+interface WorkflowManifestEntry {
+  workflowId: string; // e.g. 'explore', 'ff', 'onboard'
+  skillDirName: string; // e.g. 'openspec-explore'
+  skill: SkillTemplate;
+  command?: CommandTemplate;
+  commandId?: string;
+  tags: string[];
+  compatibility: string;
+}
+```
+
+**Rationale**:
+- Eliminates drift between multiple hand-maintained arrays
+- Makes workflow completeness testable in one place
+- Keeps split workflow modules while centralizing registration
+
+### 2. `ToolProfileRegistry` for capability wiring
+
+**Decision**: Add a tool profile layer that maps tool IDs to generation capabilities and behavior.
+
+Suggested shape:
+
+```ts
+interface ToolProfile {
+  toolId: string;
+  skillsDir?: string;
+  commandAdapterId?: string;
+  transforms: string[];
+}
+```
+
+**Rationale**:
+- Prevents capability drift between `AI_TOOLS`, adapter registry, and detection logic
+- Allows intentional "skills-only" tools without implicit special casing
+- Provides one place to answer "what does this tool support?"
+
+### 3. First-class transform pipeline
+
+**Decision**: Model transforms as ordered plugins with scope + phase + applicability.
+
+Suggested shape:
+
+```ts
+interface ArtifactTransform {
+  id: string;
+  scope: 'skill' | 'command' | 'both';
+  phase: 'preAdapter' | 'postAdapter';
+  priority: number;
+  applies(ctx: GenerationContext): boolean;
+  transform(content: string, ctx: GenerationContext): string;
+}
+```
+
+Execution order:
+1. Render canonical content from manifest
+2. Apply matching `preAdapter` transforms
+3. For commands, run adapter formatting
+4. Apply matching `postAdapter` transforms
+5. Validate and write
+
+**Rationale**:
+- Keeps adapters focused on tool formatting, not scattered behavioral rewrites
+- Makes agent-specific modifications explicit and testable
+- Replaces ad-hoc transform calls in `init`/`update`
+
+### 4. Shared `ArtifactSyncEngine`
+
+**Decision**: Introduce a single orchestration engine used by all generation entry points.
+
+Responsibilities:
+- Build generation plan from `(workflows × selected tools × artifact kinds)`
+- Run render/transform/adapter pipeline
+- Validate outputs
+- Write files and return result summary
+
+**Rationale**:
+- Removes duplicated loops and divergent behavior across init/update paths
+- Enables dry-run and future preview features without re-implementing logic
+- Improves reliability of updates and legacy migrations
+
+### 5. Validation + parity guardrails
+
+**Decision**: Add strict checks in tests (and optional runtime assertions in dev builds) for:
+
+- Required skill metadata fields (`license`, `compatibility`, `metadata`) present for all manifest entries
+- Projection consistency (skills, commands, detection names derived from manifest)
+- Tool profile consistency (adapter existence, expected capabilities)
+- Golden/parity output for key workflows/tools
+
+**Rationale**:
+- Converts prior review issues into enforced invariants
+- Preserves output fidelity while enabling internal refactors
+- Makes regressions obvious during CI
+
+## Risks / Trade-offs
+
+**Risk: Migration complexity**
+A broad refactor can destabilize generation paths.
+→ Mitigation: introduce in phases with parity tests before cutover.
+
+**Risk: Over-abstraction**
+Too many layers can obscure simple flows.
+→ Mitigation: keep interfaces minimal and colocate registries with generation code.
+
+**Trade-off: More upfront structure**
+Adding manifest/profile/transform registries increases conceptual surface area.
+→ Accepted: this cost is offset by reduced drift and easier extension.
+
+## Implementation Approach
+
+1. Build manifest + profile + transform types and registries behind current public API
+2. Rewire `getSkillTemplates`/`getCommandContents` to derive from manifest
+3. Introduce `ArtifactSyncEngine` and switch `init` to use it with parity checks
+4. Switch `update` and legacy upgrade flows to same engine
+5. Remove duplicate/hardcoded lists after parity is green

package/OpenSpec-main/openspec/changes/unify-template-generation-pipeline/proposal.md

@@ -0,0 +1,47 @@
+## Why
+
+The recent split of `skill-templates.ts` into workflow modules improved readability, but the generation pipeline is still fragmented across multiple layers:
+
+- Workflow definitions are split from projection logic (`getSkillTemplates`, `getCommandTemplates`, `getCommandContents`)
+- Tool capability and compatibility are spread across `AI_TOOLS`, `CommandAdapterRegistry`, and hardcoded lists like `SKILL_NAMES`
+- Agent/tool-specific transformations (for example OpenCode command reference rewrites) are applied in different places (`init`, `update`, and adapter code)
+- Artifact writing logic is duplicated across `init`, `update`, and legacy-upgrade flow
+
+This fragmentation creates drift risk (missing exports, missing metadata parity, mismatched counts/support) and makes future workflow/tool additions slower and less predictable.
+
+## What Changes
+
+- Introduce a canonical `WorkflowManifest` as the single source of truth for all workflow artifacts
+- Introduce a `ToolProfileRegistry` to centralize tool capabilities (skills path, command adapter, transforms)
+- Introduce a first-class transform pipeline with explicit phases (`preAdapter`, `postAdapter`) and scopes (`skill`, `command`, `both`)
+- Introduce a shared `ArtifactSyncEngine` used by `init`, `update`, and legacy upgrade paths
+- Add strict validation and test guardrails to preserve fidelity during migration and future changes
+
+## Capabilities
+
+### New Capabilities
+
+- `template-artifact-pipeline`: Unified workflow manifest, tool profile registry, transform pipeline, and sync engine for skill/command generation
+
+### Modified Capabilities
+
+- `command-generation`: Extended to support ordered transform phases around adapter rendering
+- `cli-init`: Uses shared artifact sync orchestration instead of bespoke loops
+- `cli-update`: Uses shared artifact sync orchestration instead of bespoke loops
+
+## Impact
+
+- **Primary refactor area**:
+  - `src/core/templates/*`
+  - `src/core/shared/skill-generation.ts`
+  - `src/core/command-generation/*`
+  - `src/core/init.ts`
+  - `src/core/update.ts`
+  - `src/core/shared/tool-detection.ts`
+- **Testing additions**:
+  - Manifest completeness tests (workflows, required metadata, projection parity)
+  - Transform ordering and applicability tests
+  - End-to-end parity tests for generated skill/command outputs across tools
+- **User-facing behavior**:
+  - No new CLI surface area required
+  - Existing generated artifacts remain behaviorally equivalent unless explicitly changed in future deltas

package/OpenSpec-main/openspec/changes/unify-template-generation-pipeline/specs/template-artifact-pipeline/spec.md

@@ -0,0 +1,89 @@
+# template-artifact-pipeline Specification
+
+## Purpose
+
+Define a unified architecture for workflow template generation that centralizes workflow definitions, tool capability wiring, transform execution, and artifact synchronization while preserving output fidelity.
+
+## ADDED Requirements
+
+### Requirement: Canonical Workflow Manifest
+
+The system SHALL define a canonical workflow manifest as the single source of truth for generated skill and command artifacts.
+
+#### Scenario: Register workflow once
+
+- **WHEN** a workflow (for example `explore`, `ff`, or `onboard`) is added or modified
+- **THEN** its canonical definition SHALL be registered once in the workflow manifest
+- **AND** skill/command projections SHALL be derived from that manifest
+- **AND** duplicate hand-maintained lists SHALL NOT be required
+
+#### Scenario: Required skill metadata
+
+- **WHEN** defining a workflow skill entry in the manifest
+- **THEN** it SHALL include required metadata fields (`license`, `compatibility`, and `metadata`)
+- **AND** generation SHALL use those values or explicit defaults in a consistent way for all workflows
+
+### Requirement: Tool Profile Registry
+
+The system SHALL define a tool profile registry that captures generation capabilities per tool.
+
+#### Scenario: Resolve tool capabilities
+
+- **WHEN** generating artifacts for a selected tool
+- **THEN** the system SHALL resolve a tool profile that declares skill path capability, command adapter linkage, and transform set
+- **AND** tools with skills support but no command adapter SHALL be handled explicitly without implicit fallback behavior
+
+#### Scenario: Capability consistency validation
+
+- **WHEN** running validation checks
+- **THEN** the system SHALL detect mismatches between configured tools, profile definitions, and registered adapters
+- **AND** fail with actionable errors in development/CI
+
+### Requirement: Ordered Transform Pipeline
+
+The system SHALL support ordered artifact transforms with explicit scope and phase semantics.
+
+#### Scenario: Execute pre-adapter and post-adapter transforms
+
+- **WHEN** generating an artifact
+- **THEN** matching transforms SHALL execute in deterministic order based on phase and priority
+- **AND** `preAdapter` transforms SHALL run before command adapter formatting
+- **AND** `postAdapter` transforms SHALL run after adapter formatting
+
+#### Scenario: Apply tool-specific rewrites declaratively
+
+- **WHEN** a tool requires instruction rewrites (for example command reference syntax changes)
+- **THEN** those rewrites SHALL be implemented as registered transforms with explicit applicability predicates
+- **AND** generation entry points SHALL NOT implement ad-hoc rewrite logic
+
+### Requirement: Shared Artifact Sync Engine
+
+The system SHALL provide a shared artifact sync engine used by all generation entry points.
+
+#### Scenario: Init and update use same engine
+
+- **WHEN** `openspec init` or `openspec update` writes skills/commands
+- **THEN** both flows SHALL use the same orchestration engine for planning, rendering, validating, and writing artifacts
+- **AND** behavior differences SHALL be configuration-driven rather than separate duplicated loops
+
+#### Scenario: Legacy upgrade path reuses engine
+
+- **WHEN** legacy cleanup triggers artifact regeneration
+- **THEN** the regeneration path SHALL use the same shared engine
+- **AND** generated outputs SHALL follow the same transform and validation rules
+
+### Requirement: Fidelity Guardrails
+
+The system SHALL enforce guardrails that prevent output drift during refactors.
+
+#### Scenario: Projection parity checks
+
+- **WHEN** CI runs template generation tests
+- **THEN** it SHALL verify manifest-derived projections remain consistent (workflows, command IDs, skill directories)
+- **AND** detect missing exports or missing workflow registration
+
+#### Scenario: Output parity checks
+
+- **WHEN** running parity tests for representative workflow/tool combinations
+- **THEN** generated artifacts SHALL remain behaviorally equivalent to approved baselines unless intentionally changed
+- **AND** intentional changes SHALL be captured in explicit spec/proposal updates

package/OpenSpec-main/openspec/changes/unify-template-generation-pipeline/tasks.md

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

package/OpenSpec-main/openspec/changes/workspace-agent-guidance/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-14