sauron-cli 1.3.0 → 1.4.0

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/13-agent-handoff-output-and-delivery-polish/plan.md

@@ -1,98 +0,0 @@
-# Agent Handoff Output And Delivery Polish
-
-## Status
-
-Proposed from the manual beta reality pass.
-
-This work item captures the remaining agent-handoff and delivery-output gaps
-that are smaller than the broader `initiative next` discussion but still matter
-for the beta flow.
-
-## Source Of Truth
-
-Manual beta notes:
-
-- `../11-manual-beta-reality-pass/notes.md`, especially the findings around
-  post-setup agent guidance, relative `created_files`, and commands-oriented
-  delivery warnings.
-
-Related work:
-
-- `../proposed-initiative-next-agent-handoff-ux/`
-- `../14-workspaces-beta-guide-split/`
-- `../15-context-store-project-roots-and-schema-led-initiatives/`
-
-## Why This Exists
-
-The beta pass showed that agents can succeed if they know which command to run,
-but the first handoff is still too implicit. Setup output, JSON receipts, docs,
-and generated delivery artifacts should make the next move obvious without
-requiring the user to paste tribal knowledge.
-
-This work item is deliberately narrower than an `initiative next` command. It
-polishes existing command outputs and delivery semantics so a fresh agent can
-continue safely.
-
-## Goals
-
-- Make setup and initiative creation output point to the next useful agent
-  action.
-- Ensure agent-readable JSON returns paths that can be used directly without
-  path reconstruction when practical.
-- Clarify commands-oriented delivery so "workflow commands" does not mean "the
-  agent receives no OpenSpec guidance."
-- Warn clearly when the selected tool cannot receive workflow slash commands.
-- Keep baseline OpenSpec literacy separate from workflow entrypoints.
-
-## Non-Goals
-
-- Do not implement an `initiative next` command in this slice.
-- Do not add progress dashboards or work-status rollups.
-- Do not create initiatives, changes, or workspaces automatically as part of
-  setup output.
-- Do not make every relative path field disappear if existing compatibility
-  requires it; add direct absolute path fields instead.
-
-## Output Direction
-
-Commands that create or prepare OpenSpec shared context should include a small
-handoff block in human output:
-
-```text
-Next for your agent:
-  Ask your coding agent to create or update an initiative in team-context.
-```
-
-JSON output should prefer both stable relative names and direct absolute paths
-where agents need to write files:
-
-```json
-{
-  "created_files": ["initiative.yaml", "brief.md"],
-  "created_paths": [
-    "/path/to/store/initiatives/billing-launch/initiative.yaml",
-    "/path/to/store/initiatives/billing-launch/brief.md"
-  ],
-  "next_commands": {}
-}
-```
-
-Delivery copy should distinguish:
-
-- baseline OpenSpec guidance or literacy;
-- workflow entrypoints such as skills or slash commands.
-
-If a user selects commands-oriented delivery for a tool that has no command
-adapter, output should warn that workflow slash commands are unavailable while
-still installing or recommending baseline guidance when the tool supports it.
-
-## Done When
-
-- A fresh agent can continue after context-store setup or initiative creation
-  using command output and docs, without guessing paths or beta command names.
-- JSON receipts expose direct paths for created initiative artifacts or explain
-  why only relative names are available.
-- Commands-oriented delivery output clearly reports what guidance and workflow
-  entrypoints were installed, skipped, or unavailable.
-- The broader `initiative next` proposal can build on these outputs instead of
-  solving first-run handoff from scratch.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/13-agent-handoff-output-and-delivery-polish/tasks.md

@@ -1,25 +0,0 @@
-# Agent Handoff Output And Delivery Polish Tasks
-
-- [ ] Decide which existing commands should print a "Next for your agent"
-      handoff block.
-- [ ] Define the minimal handoff content for context-store setup, initiative
-      creation, workspace opening, and repo-local linked change creation.
-- [ ] Add direct created-path fields, such as `created_paths`, where JSON output
-      currently forces agents to combine relative file names with returned
-      roots.
-- [ ] Preserve compatibility for existing relative `created_files` fields where
-      callers may already depend on them.
-- [ ] Update `initiative create --json` and sparse initiative creation output
-      from Item 15 to include direct artifact paths and next commands.
-- [ ] Decide how generated docs or setup output points to the agent CLI
-      playbook without requiring a pasted mini-playbook in every guide step.
-- [ ] Clarify delivery terminology so commands-oriented delivery means workflow
-      commands as entrypoints, not absence of baseline OpenSpec guidance.
-- [ ] Add warnings when a selected tool does not support workflow slash command
-      delivery.
-- [ ] Define how baseline OpenSpec guidance is reported when commands-oriented
-      delivery is selected for a tool that still supports skills.
-- [ ] Add tests or fixtures for human output, JSON output, and delivery-warning
-      behavior.
-- [ ] Update beta docs and generated agent guidance with the polished handoff
-      and delivery language.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/14-workspaces-beta-guide-split/plan.md

@@ -1,37 +0,0 @@
-# Workspaces Beta Guide Split
-
-## Status
-
-Proposed next work item.
-
-## Goal
-
-Make the beta docs match how people should actually use the feature:
-
-- humans use terminal prompts for local setup and local paths
-- coding agents use explicit CLI commands for OpenSpec work
-
-## Working Model
-
-User-facing docs should be light on flags and heavy on agent prompts. The agent
-CLI playbook should carry the exact commands, JSON surfaces, cwd rules, and
-current caveats.
-
-Manual beta clarification: after a workspace is opened, the user should ask the
-agent to explore or draft from the workspace. The agent should resolve the
-workspace and initiative context, identify the owning linked repo, and run
-repo-local OpenSpec commands from that repo. The workspace is the conversation
-surface, not the artifact home.
-
-## Scope
-
-- Revise `docs/workspaces-beta/user-guide.md`.
-- Revise `docs/workspaces-beta/agent-cli-playbook.md`.
-- Keep the docs minimal until the flow has been tried manually.
-- Record command or prompt gaps found during the doc pass.
-
-## Non-Goals
-
-- Do not change CLI behavior in this work item.
-- Do not promise sync, cloning, branching, worktrees, progress dashboards, or
-  enforced edit boundaries.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/14-workspaces-beta-guide-split/tasks.md

@@ -1,9 +0,0 @@
-# Workspaces Beta Guide Split Tasks
-
-- [x] Identify which setup steps should be typed by the user.
-- [x] Identify which initiative and change steps should be delegated to a coding
-  agent.
-- [x] Update the user guide around interactive setup and agent prompts.
-- [x] Update the agent CLI playbook around explicit commands and cwd rules.
-- [x] Add a tiny caveat section that reflects shipped beta behavior.
-- [ ] Capture any product gaps exposed by the docs pass.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/15-context-store-project-roots-and-schema-led-initiatives/evidence.md

@@ -1,140 +0,0 @@
-# Context Store Project Roots And Schema-Led Initiatives Evidence
-
-## Manual Beta Findings
-
-- A fresh-agent style prompt successfully created `agent-trace-hooks` in the
-  registered `team-context` context store.
-- The current CLI created this hardcoded file set:
-
-```text
-initiative.yaml
-requirements.md
-design.md
-decisions.md
-questions.md
-tasks.md
-```
-
-- The generated markdown templates started with `TBD` placeholders.
-- The agent filled those documents with plausible but unreviewed planning
-  content.
-- We manually reduced the test initiative to a sparse shape:
-
-```text
-initiative.yaml
-brief.md
-```
-
-- `openspec initiative show team-context/agent-trace-hooks --json` and
-  `openspec initiative list --store team-context --json` continued to resolve,
-  which proves current identity/listing logic does not require the six-file
-  packet.
-
-## Code Observations
-
-- Initiative file names are hardcoded in
-  `src/core/collections/initiatives/schema.ts`.
-- Initiative markdown templates are hardcoded in
-  `src/core/collections/initiatives/templates.ts`.
-- `createInitiative` writes `initiative.yaml` and then all default template
-  files in `src/core/collections/initiatives/operations.ts`.
-- `initiative create --json` reports `created_files` from
-  `INITIATIVE_FILE_NAMES` in `src/commands/initiative.ts`.
-- Initiative list/show read only `initiative.yaml`.
-- Project-local schema resolution already uses
-  `<projectRoot>/openspec/schemas/<name>/schema.yaml` in
-  `src/core/artifact-graph/resolver.ts`.
-- Project config already reads `<projectRoot>/openspec/config.yaml` in
-  `src/core/project-config.ts`.
-- Change artifact status/instructions are coupled to repo-local change context
-  through `src/core/artifact-graph/instruction-loader.ts`.
-- Planning-home detection currently treats an ancestor containing `openspec/`
-  as a possible repo planning root, so adding config to context stores needs a
-  safety check.
-
-## UX/Product Pass
-
-Recommended user meaning:
-
-```text
-context store = shared OpenSpec context project
-initiative    = iterative high-level planning object
-repo change   = implementation plan
-workspace     = local view
-```
-
-Docs should avoid saying initiatives are only for cross-repo or cross-team
-work. A user may choose a context store simply because they want OpenSpec
-artifacts outside the implementation repo.
-
-`initiative create` should make the smallest useful shared object and then
-teach the agent how to continue through status/instructions. It should not
-pretend requirements, decisions, and tasks exist before review.
-
-## Architecture Pass
-
-Feasible minimal path:
-
-1. Treat the context store root as a project root for config/schema resolution.
-2. Create `openspec/config.yaml` during context-store setup.
-3. Resolve initiative schemas with `projectRoot = contextStoreRoot`.
-4. Add initiative-specific status/instructions helpers using artifact graph
-   primitives.
-5. Change initiative creation to write a sparse shell.
-
-Main risks:
-
-- strict `initiative.yaml` parsing if a new top-level `schema` field is added
-- tests currently asserting the six-file MVP contract
-- docs and generated agent guidance currently telling agents to edit the five
-  generated Markdown files
-- ambiguity between initiative planning artifacts and repo-local implementation
-  tasks
-- context-store roots becoming accidental repo planning homes after they gain
-  `openspec/config.yaml`
-
-## Subagent / Research Notes
-
-Three focused passes converged on the same direction.
-
-Architecture pass:
-
-- Model a context store as an OpenSpec planning root:
-
-```text
-context-store/
-  .openspec-store/store.yaml
-  openspec/config.yaml
-  openspec/schemas/
-  initiatives/
-```
-
-- Keep `.openspec-store/store.yaml` as store identity and
-  `openspec/config.yaml` as behavior/configuration.
-- Reuse project-local config and schema resolution with the context-store root
-  as the project root.
-- Add an initiative-specific artifact context instead of forcing initiatives
-  through repo-local change context.
-- Guard planning-home discovery so a context store with `openspec/config.yaml`
-  does not become an accidental implementation repo.
-
-UX/product pass:
-
-- Describe a context store as an OpenSpec-managed planning home. It may be used
-  for cross-repo coordination, but also simply to keep OpenSpec artifacts out of
-  an implementation repo.
-- Make `initiative create` sparse: `initiative.yaml` plus a seed artifact such
-  as `brief.md`.
-- Add status/instructions output so agents create requirements and design
-  artifacts only when there is reviewed content to capture.
-- Stop treating default initiative artifacts as files the user or agent should
-  immediately fill in.
-
-Release-risk pass:
-
-- Keep old six-file beta initiatives readable.
-- Update tests that assert the old generated file list.
-- Avoid strict top-level additions to `initiative.yaml` until metadata
-  versioning is designed.
-- Defer context-store-hosted executable changes to the configurable change-home
-  work instead of bundling them into this slice.

package/OpenSpec-main/openspec/initiatives/context-store-and-initiatives/work-items/15-context-store-project-roots-and-schema-led-initiatives/plan.md

@@ -1,344 +0,0 @@
-# Context Store Project Roots And Schema-Led Initiatives
-
-## Status
-
-Proposed from the manual beta reality pass.
-
-This work item replaces the current "initiative create writes a full hardcoded
-six-file packet" model with a project-like context-store root and an iterative,
-schema-led initiative artifact flow.
-
-## Source Of Truth
-
-Start from `../../direction.md` and preserve the current boundary:
-
-```text
-Context stores sync truth.
-Collections shape truth.
-Initiatives coordinate work.
-Workspaces open local views.
-Changes implement repo-owned slices.
-```
-
-Manual beta evidence: agents can create the current MVP initiative shape, but
-the generated `requirements.md`, `design.md`, `decisions.md`, `questions.md`,
-and `tasks.md` invite premature, unreviewed planning content.
-
-## Why This Exists
-
-`openspec initiative create` currently creates a complete-looking planning
-packet from hardcoded TypeScript constants and `TBD` templates. That made the
-MVP tangible, but it is the wrong default for real initiative work.
-
-Initiatives are high-level shared planning surfaces for PMs, designers,
-architects, and agents. They should capture intent, reviewed requirements,
-design direction, open questions, and decisions as those artifacts become real.
-They should not create empty or fake documents that look finished just because
-the folder exists.
-
-The broader product shape is that a context store should feel like an OpenSpec
-root in the same way a repo does after `openspec init`: it can have local
-OpenSpec configuration and project-local schemas. The difference is lifecycle:
-a context store is the shared context root, not an implementation repo.
-
-## Product Model
-
-Repo after `openspec init`:
-
-```text
-repo/
-  openspec/
-    config.yaml
-    schemas/
-    changes/
-    specs/
-```
-
-Context store after setup:
-
-```text
-context-store/
-  .openspec-store/
-    store.yaml
-  openspec/
-    config.yaml
-    schemas/
-  initiatives/
-```
-
-The `openspec/` directory inside a context store exists for OpenSpec config and
-schema resolution. It does not by itself make the context store an executable
-implementation planning home.
-
-## Goals
-
-- Let context stores carry OpenSpec config, including a default initiative
-  schema.
-- Let context stores carry project-local schemas under `openspec/schemas/`.
-- Replace hardcoded initiative file creation with a schema-led artifact model.
-- Make `initiative create` sparse and safe by default.
-- Let agents grow initiative artifacts one step at a time through status and
-  instructions output.
-- Keep existing six-file MVP initiatives readable.
-- Keep repo-local changes as the default implementation artifact.
-
-## Non-Goals
-
-- Do not make context-store-hosted executable changes part of this slice. That
-  remains Item 18.
-- Do not add cross-repo apply, archive, validation, or spec-sync orchestration.
-- Do not make workspace-local artifacts the shared planning source of truth.
-- Do not migrate existing initiatives automatically.
-- Do not install AI-tool runtime files into context stores by default unless a
-  later UX decision explicitly opts into that.
-
-## Default Initiative Shape
-
-New initiative creation should create a shell, not the whole plan:
-
-```text
-initiatives/<id>/
-  initiative.yaml
-  brief.md
-```
-
-`brief.md` is a seed document, not a completion marker for reviewed
-requirements or design. It should contain the title, summary, and a short
-"current understanding" section with no `TBD` placeholders.
-
-Reviewed planning artifacts are created later through the initiative schema.
-
-Default built-in schema, conceptually:
-
-```yaml
-name: product-initiative
-version: 1
-description: High-level initiative planning for PMs, designers, architects, and agents
-usage: initiative
-artifacts:
-  - id: requirements
-    generates: requirements.md
-    description: Product intent, goals, non-goals, requirements, and open questions
-    template: requirements.md
-    requires: []
-
-  - id: design
-    generates: design.md
-    description: Product, UX, and architecture direction with constraints and tradeoffs
-    template: design.md
-    requires:
-      - requirements
-```
-
-Do not include `tasks.md` in the default initiative schema. Implementation
-tasks belong in repo-local changes. Coordination tasks, workstreams, decision
-logs, and question logs can be separate later schemas or explicit artifacts once
-the usage pattern is clearer.
-
-## UX Direction
-
-Store setup should make the store project-like enough for schemas:
-
-```bash
-openspec context-store setup team-context --init-git
-```
-
-Expected created shape:
-
-```text
-team-context/
-  .openspec-store/store.yaml
-  openspec/config.yaml
-  initiatives/
-```
-
-Preferred config direction:
-
-```yaml
-initiative_schema: product-initiative
-```
-
-This avoids overloading the existing repo-local `schema` field, which currently
-means "default change schema." If implementation chooses to reuse `schema`
-instead, docs and JSON output must make the context-store scope explicit.
-
-Then initiative creation stays small:
-
-```bash
-openspec initiative create agent-trace-hooks \
-  --store team-context \
-  --title "Agent Trace Hooks" \
-  --summary "Explore lightweight capture of agent trace events and hook outcomes."
-```
-
-Expected next action:
-
-```bash
-openspec initiative status team-context/agent-trace-hooks --json
-openspec initiative instructions requirements team-context/agent-trace-hooks --json
-```
-
-The agent writes `requirements.md` only when the conversation has enough
-reviewed content. `design.md` becomes ready after requirements exist.
-
-## Technical Approach
-
-Reuse the artifact graph primitives, but add an initiative-specific loader
-instead of forcing initiatives through `loadChangeContext`.
-
-Current reusable pieces:
-
-- `src/core/artifact-graph/graph.ts`
-- `src/core/artifact-graph/state.ts`
-- `src/core/artifact-graph/outputs.ts`
-- `src/core/artifact-graph/resolver.ts`
-- `src/core/artifact-graph/instruction-loader.ts` template loading
-- `src/core/project-config.ts`
-
-New initiative-specific pieces:
-
-- a context-store OpenSpec-root helper that treats the store root as the
-  `projectRoot` for config and schema lookup
-- an initiative artifact context loader rooted at
-  `context-store/initiatives/<id>/`
-- initiative `status` and `instructions` commands that mirror the repo-local
-  artifact workflow but return initiative-specific fields
-- a sparse `initiative create` path that writes `initiative.yaml` and `brief.md`
-  only
-
-Do not use the existing repo planning-home resolver unchanged. Once context
-stores contain `openspec/config.yaml`, the current "nearest `openspec/` folder
-means repo planning home" heuristic can accidentally make a context store look
-like an implementation repo. This work must either:
-
-- teach planning-home resolution to detect `.openspec-store/store.yaml` and
-  return or reject a context-store kind for implementation commands, or
-- explicitly reject `openspec new change` from a context-store root until Item
-  15 defines target-bound executable changes.
-
-## Schema And Config Compatibility
-
-Prefer a next-release-safe config path:
-
-- Add `initiative_schema` to project config, or an equivalent
-  collection-specific config field.
-- Continue using existing `schema` as the default repo-local change schema.
-- Store per-initiative schema overrides in existing `metadata` if needed.
-- Avoid adding a new top-level `schema` field to `initiative.yaml` until
-  initiative metadata versioning is designed.
-
-Why: `initiative.yaml` is currently strict and versioned as `version: 1`.
-Adding a top-level field would make older CLIs reject new initiatives. Existing
-`metadata` can carry forward-compatible fields without breaking old readers.
-
-Schema namespace needs one explicit decision:
-
-- Either add a `usage: change | initiative` discriminator to schema files and
-  filter commands accordingly, or
-- use a separate initiative schema namespace while reusing the same artifact
-  graph format.
-
-The simplest user-facing model is still `openspec/schemas/`, but commands must
-avoid listing `product-initiative` as a valid repo-local change workflow.
-
-## JSON Contract
-
-`initiative create --json` should report the shell and next actions:
-
-```json
-{
-  "context_store": {
-    "id": "team-context",
-    "root": "/path/to/store"
-  },
-  "initiative": {
-    "id": "agent-trace-hooks",
-    "root": "/path/to/store/initiatives/agent-trace-hooks",
-    "metadata_path": "/path/to/store/initiatives/agent-trace-hooks/initiative.yaml",
-    "schema": "product-initiative"
-  },
-  "created_files": [
-    "initiative.yaml",
-    "brief.md"
-  ],
-  "next_commands": {
-    "status": "openspec initiative status team-context/agent-trace-hooks --json",
-    "requirements": "openspec initiative instructions requirements team-context/agent-trace-hooks --json"
-  },
-  "status": []
-}
-```
-
-`initiative status --json` should include:
-
-- context store identity and root
-- initiative identity, root, metadata path, and selected schema
-- artifact paths keyed by artifact id
-- artifact statuses: `done`, `ready`, `blocked`
-- next steps
-- action context that says this is shared planning context, not an editable
-  implementation target
-
-`initiative instructions --json` should include:
-
-- resolved output path
-- existing output paths
-- schema instruction
-- template content
-- dependencies and unlocks
-- store config context/rules if supported
-
-## Release Risk And Migration
-
-This is compatible if implemented as a sparse, additive layer:
-
-- Existing six-file initiatives remain readable because list/show only require
-  `initiative.yaml`.
-- Existing optional markdown files can remain in old initiative folders.
-- New status/instructions can ignore files outside the selected schema.
-- Old CLIs can still read new initiatives if schema data stays under
-  `metadata` or store config rather than new strict top-level fields.
-
-High-risk areas:
-
-- Planning-home detection after context stores gain `openspec/config.yaml`.
-- Tests and docs that assert the six-file MVP initiative shape.
-- Schema lists and completions if initiative schemas share the same namespace
-  as change schemas.
-- Agent guidance that still tells agents to edit every generated initiative
-  markdown file after creation.
-
-## Test And Doc Touch Points
-
-Likely tests to update or add:
-
-- `test/core/collections/initiatives/schema.test.ts`
-- `test/core/collections/initiatives/templates.test.ts`
-- `test/core/collections/initiatives/operations.test.ts`
-- `test/commands/initiative.test.ts`
-- `test/commands/context-store.test.ts`
-- `test/commands/artifact-workflow.test.ts`
-- planning-home tests for context-store roots with `openspec/config.yaml`
-- schema listing/completion tests if schema usage filtering is added
-
-Likely docs to update:
-
-- `docs/workspaces-beta/agent-cli-playbook.md`
-- `docs/workspaces-beta/user-guide.md`
-- `docs/cli.md`
-- schema docs if `usage` or `initiative_schema` is added
-- `openspec/initiatives/context-store-and-initiatives/work-items/05-ship-initiative-mvp/`
-  with a note that the MVP shape was superseded by this work item
-
-## Done When
-
-- A new context store has OpenSpec config and can resolve project-local
-  initiative schemas.
-- `initiative create` creates only the sparse initiative shell.
-- Agents can use initiative status/instructions to create high-level planning
-  artifacts iteratively.
-- `openspec new change` does not accidentally treat a context store as a normal
-  implementation repo just because the store has `openspec/config.yaml`.
-- Existing MVP initiatives continue to list and show.
-- Docs describe initiative artifacts as reviewed, iterative context rather than
-  files to fill in immediately.