Agent skill

openspec-context-loading

Loads project context, lists existing specs and changes, searches capabilities and requirements. Use when user asks about project state, existing specs, active changes, available capabilities, or needs context discovery. Triggers include "openspec context", "what specs exist", "show changes", "list capabilities", "project context", "find specs", "what's in the spec", "show me specs".

View SKILL.md on GitHub Repository
Stars 7
Forks 2

Install this agent skill to your Project

npx add-skill https://github.com/forztf/open-skilled-sdd/tree/main/skills/openspec-context-loading

SKILL.md

Specification Context Loading

Discovers and loads project specifications, active changes, and requirements to provide context.

Quick Start

Context loading helps answer:

  • What specs exist in this project?
  • What changes are currently active?
  • What requirements are defined?
  • What capabilities does the system have?
  • Where is a specific feature specified?

Basic pattern: Search → Read → Summarize

Discovery Commands

List All Specifications

bash
# Find all spec files
find spec/specs -name "spec.md" -type f

# Find all capability directories
find spec/specs -mindepth 1 -maxdepth 1 -type d

# Show spec tree
tree spec/specs/  # if tree is installed
# or
ls -R spec/specs/

Output format:

spec/specs/
├── authentication/
│   └── spec.md
├── billing/
│   └── spec.md
└── notifications/
    └── spec.md

List Active Changes

bash
# Show all active changes
find spec/changes -maxdepth 1 -type d -not -path "spec/changes" -not -path "*/archive" | sort

# Show with modification dates
find spec/changes -maxdepth 1 -type d -not -path "spec/changes" -not -path "*/archive" -exec ls -ld {} \;

# Count active changes
find spec/changes -maxdepth 1 -type d -not -path "spec/changes" -not -path "*/archive" | wc -l

List Archived Changes

bash
# Show all archived changes
ls -1 spec/archive/

# Show with dates
ls -la spec/archive/

# Find recently archived (last 7 days)
find spec/archive/ -maxdepth 1 -type d -mtime -7

Search for Requirements

bash
# Find all requirements
grep -r "### Requirement:" spec/specs/

# Find requirements in specific capability
grep "### Requirement:" spec/specs/authentication/spec.md

# List unique requirement names
grep -h "### Requirement:" spec/specs/**/*.md | sed 's/### Requirement: //' | sort

Search for Scenarios

bash
# Find all scenarios
grep -r "#### Scenario:" spec/specs/

# Count scenarios per spec
for spec in spec/specs/**/spec.md; do
    count=$(grep -c "#### Scenario:" "$spec")
    echo "$spec: $count scenarios"
done

Search by Keyword

bash
# Find specs mentioning "authentication"
grep -r -i "authentication" spec/specs/

# Find requirements about "password"
grep -B 1 -A 5 -i "password" spec/specs/**/*.md | grep -A 5 "### Requirement:"

# Find scenarios about "error"
grep -B 1 -A 10 -i "error" spec/specs/**/*.md | grep -A 10 "#### Scenario:"

Common Queries

Query 1: "What specs exist?"

bash
# List all capabilities
find spec/specs -mindepth 1 -maxdepth 1 -type d -exec basename {} \;

# Count requirements per capability
for cap in spec/specs/*/; do
    name=$(basename "$cap")
    count=$(grep -c "### Requirement:" "$cap/spec.md" 2>/dev/null || echo "0")
    echo "$name: $count requirements"
done

Response format:

markdown
## Existing Specifications

The project has specifications for the following capabilities:

- **authentication**: 8 requirements
- **billing**: 12 requirements
- **notifications**: 5 requirements

Total: 3 capabilities, 25 requirements

Query 2: "What changes are active?"

bash
# List with proposal summaries
for change in spec/changes/*/; do
    if [ "$change" != "spec/changes/archive/" ]; then
        id=$(basename "$change")
        echo "=== $id ==="
        head -n 20 "$change/proposal.md" | grep -A 3 "## Why"
    fi
done

Response format:

markdown
## Active Changes

Currently active changes:

### add-user-auth
**Why**: Users need secure authentication...

### update-billing-api
**Why**: Payment processing requires v2 API...

Total: 2 active changes

Query 3: "Show me the authentication spec"

bash
# Read full spec
cat spec/specs/authentication/spec.md

# Or show summary
echo "Requirements:"
grep "### Requirement:" spec/specs/authentication/spec.md

echo "\nScenarios:"
grep "#### Scenario:" spec/specs/authentication/spec.md

Response format:

markdown
## Authentication Specification

(Include full content of spec.md)

Summary:
- 8 requirements
- 16 scenarios
- Last modified: [date from git log]

Query 4: "Find specs about password"

bash
# Search for keyword
grep -r -i "password" spec/specs/ -A 5

# Show which specs mention it
grep -r -i "password" spec/specs/ -l

Response format:

markdown
## Specs Mentioning "Password"

Found in:
- spec/specs/authentication/spec.md (3 requirements)
- spec/specs/security/spec.md (1 requirement)

Relevant requirements:
### Requirement: Password Validation
### Requirement: Password Reset
### Requirement: Password Strength

Query 5: "What's in change X?"

bash
# Show full change context
CHANGE_ID="add-user-auth"

echo "=== Proposal ==="
cat spec/changes/$CHANGE_ID/proposal.md

echo "\n=== Tasks ==="
cat spec/changes/$CHANGE_ID/tasks.md

echo "\n=== Spec Deltas ==="
find spec/changes/$CHANGE_ID/specs -name "*.md" -exec echo "File: {}" \; -exec cat {} \;

Dashboard View

Create a comprehensive project overview:

bash
#!/bin/bash
# Project specification dashboard

echo "===  Specification Dashboard ==="
echo ""

# Capabilities
echo "## Capabilities"
CAPS=$(find spec/specs -mindepth 1 -maxdepth 1 -type d | wc -l)
echo "Total capabilities: $CAPS"
for cap in spec/specs/*/; do
    name=$(basename "$cap")
    reqs=$(grep -c "### Requirement:" "$cap/spec.md" 2>/dev/null || echo "0")
    echo "  - $name: $reqs requirements"
done
echo ""

# Requirements
echo "## Requirements"
TOTAL_REQS=$(grep -r "### Requirement:" spec/specs/ | wc -l)
TOTAL_SCENARIOS=$(grep -r "#### Scenario:" spec/specs/ | wc -l)
echo "Total requirements: $TOTAL_REQS"
echo "Total scenarios: $TOTAL_SCENARIOS"
echo "Avg scenarios per requirement: $(echo "scale=1; $TOTAL_SCENARIOS/$TOTAL_REQS" | bc)"
echo ""

# Changes
echo "## Changes"
ACTIVE=$(find spec/changes -maxdepth 1 -type d -not -path "spec/changes" -not -path "*/archive" | wc -l)
ARCHIVED=$(ls -1 spec/archive/ | wc -l)
echo "Active changes: $ACTIVE"
echo "Archived changes: $ARCHIVED"
echo ""

# Recent activity
echo "## Recent Activity"
echo "Recently modified specs:"
find spec/specs -name "spec.md" -type f -exec ls -lt {} \; | head -5

Response format:

markdown
# Specification Dashboard

## Capabilities
Total capabilities: 3
  - authentication: 8 requirements
  - billing: 12 requirements
  - notifications: 5 requirements

## Requirements
Total requirements: 25
Total scenarios: 52
Avg scenarios per requirement: 2.1

## Changes
Active changes: 2
Archived changes: 15

## Recent Activity
Recently modified specs:
- spec/specs/billing/spec.md (2 days ago)
- spec/specs/authentication/spec.md (1 week ago)

Advanced Queries

Find Related Requirements

bash
# Find requirements that mention another requirement
grep -r "User Login" spec/specs/ -A 10 | grep "### Requirement:"

# Find cross-references
grep -r "See Requirement:" spec/specs/

Analyze Coverage

bash
# Find requirements without scenarios
for spec in spec/specs/**/spec.md; do
    awk '/### Requirement:/ {req=$0; getline; if ($0 !~ /#### Scenario:/) print req}' "$spec"
done

# Find scenarios without proper Given/When/Then
grep -A 5 "#### Scenario:" spec/specs/**/*.md | grep -v "GIVEN\|WHEN\|THEN"

Compare Active vs Archive

bash
# Show evolution over time
echo "Archive history:"
ls -1 spec/archive/ | head -10

echo "Recent archives (last 30 days):"
find spec/archive/ -maxdepth 1 -type d -mtime -30 -exec basename {} \;

Search Patterns

Pattern 1: Capability Discovery

User asks: "What can the system do?"

bash
# List capabilities
find spec/specs -mindepth 1 -maxdepth 1 -type d -exec basename {} \;

# Show high-level requirements
for cap in spec/specs/*/; do
    echo "=== $(basename $cap) ==="
    grep "### Requirement:" "$cap/spec.md" | head -3
done

Pattern 2: Feature Search

User asks: "Is there a spec for password reset?"

bash
# Search for keyword
grep -r -i "password reset" spec/specs/ -B 1 -A 10

# If found, show full requirement
grep -B 1 -A 20 "Requirement:.*Password Reset" spec/specs/**/*.md

Pattern 3: Change Tracking

User asks: "What's being worked on?"

bash
# Show active changes with status
for change in spec/changes/*/; do
    if [ "$change" != "spec/changes/archive/" ]; then
        id=$(basename "$change")
        echo "$id:"
        test -f "$change/IMPLEMENTED" && echo "  Status: Implemented" || echo "  Status: In Progress"
        echo "  Tasks: $(grep -c "^[0-9]\+\." "$change/tasks.md")"
    fi
done

Best Practices

Pattern 1: Provide Context Before Details

Good flow:

markdown
1. Show dashboard (high-level overview)
2. User asks about specific capability
3. Show that capability's requirements
4. User asks about specific requirement
5. Show full requirement with scenarios

Pattern 2: Use Grep Efficiently

bash
# Combine filters for precision
grep -r "### Requirement:" spec/specs/ | grep -i "auth"

# Use context flags for readability
grep -B 2 -A 10 "#### Scenario:" spec/specs/authentication/spec.md

Pattern 3: Aggregate Information

Don't just dump file contents. Summarize:

markdown
**Bad**: (dump entire spec file)

**Good**:
"The authentication spec has 8 requirements covering:
- User login
- Password management
- Session handling
- Multi-factor authentication

Would you like details on any specific requirement?"

Anti-Patterns to Avoid

Don't:

  • Read entire spec files without user request
  • List every single requirement by default
  • Show raw grep output without formatting
  • Assume user knows capability names

Do:

  • Start with high-level overview
  • Ask which area user wants to explore
  • Format output clearly
  • Provide navigation hints

Reference Materials

  • SEARCH_PATTERNS.md - Advanced grep/find patterns

Token budget: This SKILL.md is approximately 460 lines, under the 500-line recommended limit.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

forztf/open-skilled-sdd

speckit-implement-zh

通过测试与验证为先的方式，按序执行并实现已批准的规范提案。用于实施变更、应用提案、执行规范任务或按已批准计划构建。触发词包括 "speckit-implement", "speckit开发", "开发", "实施" "实现提案", "应用变更", "执行规范", "按顺序完成任务", "构建功能", "开始实施"。

7 2
Explore
forztf/open-skilled-sdd

speckit-clarify-zh

通过提出最多5个高度针对性的澄清问题来识别当前功能规范中未明确定义的领域，并将答案编码回规范中。触发词包括："speckit-clarify"、"speckit澄清"、"规范澄清"、"功能澄清"、"识别模糊点"、"澄清需求"。

7 2
Explore
forztf/open-skilled-sdd

openspec-proposal-creation-cn

通过openspec规范驱动的方法创建结构化的变更提案与规范差异。用于规划功能、创建提案、编写规范、引入新能力或启动开发流程。触发词包括 "openspec提案", "规划", "创建提案", "规划变更", "规范功能", "新功能", "新特性", "新需求", "添加功能规划", "设计规范"。

7 2
Explore
forztf/open-skilled-sdd

speckit-checklist-zh

基于用户需求为当前功能生成定制检查清单的专业工具。专门用于需求质量验证，生成"英语的单元测试"，验证需求的完整性、清晰度和一致性。触发词：speckit-checklist、检查清单、需求验证、质量检查、checklist、requirements validation、质量审查、spec review

7 2
Explore
forztf/open-skilled-sdd

speckit-constitution-zh

从交互式或提供的原则输入创建或更新项目章程，确保所有依赖模板保持同步。用于项目管理、规范制定、章程维护和团队协作场景。触发词包括 "speckit章程"、"创建章程"、"更新章程"、"项目章程"、"制定规范"、"团队章程"。

7 2
Explore
forztf/open-skilled-sdd

speckit-analyze-zh

对spec.md、plan.md和tasks.md三个核心文档进行非破坏性跨工件一致性和质量分析。在任务生成后识别不一致、重复、模糊和规范不足的项目。触发词包括："speckit-analyze"、"speckit分析"、"文档一致性分析"、"规范分析"、"质量检查"、"工件分析"、"spec分析"、"plan分析"、"task分析"。

7 2
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results