mirror of https://github.com/Fission-AI/OpenSpec.git synced 2026-11-06 09:03:27 +08:00

Files

T

Tabish Bidiwale 5fd8e9d66c feat: simplify skill installation with profiles and smart defaults init (#719 )

* feat: add change proposal for simplified skill installation

Introduces a change proposal to simplify the init flow and skill installation:

- Zero-question init with sensible defaults (core profile, both delivery)
- Auto-detect AI tools from existing directories (.claude/, .cursor/, etc.)
- Profile system: core (4 workflows), extended (11 workflows), custom
- Delivery config: both, skills, commands
- New `propose` workflow combining new + ff
- Fix tool selection UX (space to select, enter to confirm)

Key design decisions:
- Extend existing global config (~/.config/openspec/config.json)
- Profile install/uninstall immediately mutates filesystem
- Safe deletion via SKILL_NAMES and COMMAND_IDS constant lookups
- Filesystem as truth for installed workflows

Also adds rules to openspec/config.yaml to prevent overengineering
(explicit lookups over pattern matching).

* chore: add missing .openspec.yaml metadata file

* fix: address PR review feedback

Issues fixed:
- Clarify workflow count: extended = existing 10 + new propose = 11
- Rename spec: tool-auto-detection → available-tools (matches proposal)
- Change "identical" to "functionally equivalent" in propose spec
- Add profile change notification when install/uninstall changes profile
- Specify edge case: uninstall workflow from current non-custom profile
- Specify behavior when --apply-profile confirmation is declined
- Fix section numbering in design.md (6, 6a, 6b, 8)
- Add scaffolding verification tasks (verify .openspec.yaml exists)
- Specify case sensitivity mechanism: use fs.existsSync, let OS handle it

* fix: address CodeRabbit review comments

- Add language specifiers to fenced code blocks in proposal.md
- Add COMMAND_IDS update for propose in modified files list
- Make init success message tool-aware (colon vs hyphen syntax)
- Fix grammar: "Skills-only" and "Commands-only" in delivery-config
- Specify config get delivery output when field absent: "both (default)"
- Add profile set scenarios: config-only vs --apply-profile with filesystem mutation
- Add error scenarios for invalid profile name and unknown workflow
- Add scenario for existing config without profile field
- Mark active profile in profile list output
- Enumerate artifacts in propose basic scenario
- Fix propose equivalence to use skill syntax consistently
- Specify continue/create new branches in propose
- Remove out-of-scope command assertion from skill-generation spec
- Reference SKILL_NAMES constant instead of vague "existing templates"
- Fix design.md: SKILL_NAMES AND COMMAND_IDS (not "only")
- Specify overwrite semantics for refresh/update
- Add task 6.8: propose to COMMAND_IDS
- Fix function name: getAvailableTools() not detectInstalledTools()

* refactor: simplify skill installation design based on review

- Update design to use existing CLAUDE.md mechanisms
- Add cli-update spec for managing skill updates
- Clarify profile system and user config interactions
- Add explorations directory with design notes
- Update docs with clearer concepts

* docs: rename zero-question init to smart defaults init

Clarify that init auto-detects tools and asks for confirmation,
rather than being completely question-free. Update examples to
show the tool confirmation UI.

* docs: add explore workflow tasks and UX exploration

- Add tasks to update explore.ts references to /opsx:propose
- Create exploration note for deeper explore → propose UX questions
- Captures open questions about exploration artifacts, lifecycle,
  context handoff, and transition smoothness

* fix: address PR review feedback from 1code-async

- Add ## Purpose sections to all 10 spec files (required by schema)
- Add specs/ to propose workflow's first-time user guidance scenario
- Add --tools flag scenario for interactive mode in cli-init/spec.md
- Clarify that profile changes take effect on next init/update
- Fix design snippet to use AI_TOOLS config instead of TOOL_DIRS constant
- Add explicit Windsurf detection scenario to available-tools/spec.md
- Mark tasks 10.2-10.3 as follow-up work (out of scope)
- Fix capability name: init → cli-init in proposal.md

2026-02-18 02:11:35 -08:00

3.9 KiB

Raw Blame History

docs-agent-instructions Specification

Purpose

Define authoring standards for generated agent instruction docs so templates, examples, and validation checklists are clear and copy-ready.

Requirements

Requirement: Quick Reference Placement

The AI instructions SHALL begin with a quick-reference section that surfaces required file structures, templates, and formatting rules before any narrative guidance.

Scenario: Loading templates at the top

WHEN openspec/AGENTS.md is regenerated or updated
THEN the first substantive section after the title SHALL provide copy-ready headings for proposal.md, tasks.md, spec deltas, and scenario formatting
AND link each template to the corresponding workflow step for deeper reading

Requirement: Embedded Templates and Examples

openspec/AGENTS.md SHALL include complete copy/paste templates and inline examples exactly where agents make corresponding edits.

Scenario: Providing file templates

WHEN authors reach the workflow guidance for drafting proposals and deltas
THEN provide fenced Markdown templates that match the required structure (## Why, ## ADDED Requirements, #### Scenario: etc.)
AND accompany each template with a brief example showing correct header usage and scenario bullets

Requirement: Pre-validation Checklist

openspec/AGENTS.md SHALL offer a concise pre-validation checklist that highlights common formatting mistakes before running openspec validate.

Scenario: Highlighting common validation failures

WHEN a reader reaches the validation guidance
THEN present a checklist reminding them to verify requirement headers, scenario formatting, and delta sections
AND include reminders about at least #### Scenario: usage and descriptive requirement text before scenarios

Requirement: Progressive Disclosure of Workflow Guidance

The documentation SHALL separate beginner essentials from advanced topics so newcomers can focus on core steps without losing access to advanced workflows.

Scenario: Organizing beginner and advanced sections

WHEN reorganizing openspec/AGENTS.md
THEN keep an introductory section limited to the minimum steps (scaffold, draft, validate, request review)
AND move advanced topics (multi-capability changes, archiving details, tooling deep dives) into clearly labeled later sections
AND provide anchor links from the quick-reference to those advanced sections

Requirement: Behavior-First Spec Authoring Guidance

Agent instruction docs SHALL explicitly teach that specs capture observable behavior contracts, while implementation details belong in design/tasks.

Scenario: Distinguishing spec vs implementation content

WHEN openspec/AGENTS.md explains how to write spec.md
THEN it SHALL instruct agents to include externally verifiable behavior, inputs/outputs, errors, and constraints
AND it SHALL instruct agents to avoid internal library/framework choices and class/function-level implementation details in specs

Scenario: Routing detail to the right artifact

WHEN implementation detail is necessary
THEN instructions SHALL direct the agent to place it in design.md or tasks.md, not in the behavioral requirements section of spec.md

Requirement: Lightweight-by-Default Guidance

Agent instruction docs SHALL promote minimal ceremony and proportional rigor for spec authoring.

Scenario: Applying progressive rigor

WHEN an agent drafts specs for routine changes
THEN instructions SHALL favor concise, lightweight requirements and scenarios
AND reserve deeper, fuller specification style for higher-risk changes (such as API breaks, migrations, cross-team, or security/privacy sensitive work)

Scenario: Time-to-clarity optimization

WHEN guidance discusses drafting workflow
THEN it SHALL emphasize producing the smallest spec that is still testable and reviewable

3.9 KiB Raw Blame History