mirror of https://github.com/Fission-AI/OpenSpec.git synced 2026-09-14 20:16:53 +08:00

Files

T

Tabish Bidiwale 4a863285b0 chore: archive 4 completed changes and update specs (#172 )

Archived:
- enhance-validation-error-messages (updated cli-validate spec)
- improve-agent-instruction-usability (created docs-agent-instructions spec)
- update-cli-init-root-agents (updated cli-init and cli-update specs)
- update-release-automation (no spec updates)

2025-10-14 15:42:49 +11:00

2.4 KiB

Raw Permalink Blame History

docs-agent-instructions Specification

Purpose

TBD - created by archiving change improve-agent-instruction-usability. Update Purpose after archive.

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

2.4 KiB Raw Permalink Blame History