SPECLAN Query

Fast, flexible querying of SPECLAN entities with JSON output. Query by type, filter by status or parent, with optional full metadata extraction.

Why Use This Skill

• Fast: Filename-based parsing without reading files (unless filters require it)
• Reliable: Uses {PREFIX}-{ID}-{slug} naming pattern as source of truth
• Flexible: Query any entity type, filter by status/parent
• Structured: Clean JSON output for programmatic consumption
• zsh-safe: Avoids reserved word conflicts (uses entity_status not status)

Entity Types

Type	Prefix	Pattern	Location
goal	G-	G-###-*.md	goals/
feature	F-	F-####-*.md	features/ (recursive)
requirement	R-	R-####-*.md	features/.../requirements/
change-request	CR-	CR-####-*.md	Anywhere in change-requests/

Usage

Script Location

${CLAUDE_PLUGIN_ROOT}/skills/speclan-query/scripts/query.sh

Command Line

./query.sh [OPTIONS] [speclan-dir]

Options:

• -t, --type TYPE - Entity type to query (required)
• -s, --filter-status STATUS - Filter by status (draft|review|approved|in-development|under-test|released|deprecated)
• -p, --parent ID - Filter by parent ID (e.g., F-1234)
• -f, --full - Include title and status in output (reads frontmatter)
• -h, --help - Show usage

Arguments:

• speclan-dir - Path to speclan directory (default: ./speclan)

Output:

• JSON array to stdout
• Errors to stderr
• Exit code: 0 = success, 1 = error

Examples

List all features (fast - filename only)

./query.sh --type feature speclan

Output:

[
  {"id":"F-1049","slug":"pet-management","type":"feature","path":"speclan/features/F-1049-pet-management/F-1049-pet-management.md"},
  {"id":"F-2847","slug":"user-auth","type":"feature","path":"speclan/features/F-2847-user-auth/F-2847-user-auth.md"}
]

List features with full details

./query.sh --type feature --full speclan

Output:

[
  {"id":"F-1049","slug":"pet-management","type":"feature","path":"...","title":"Pet Management","status":"draft"},
  {"id":"F-2847","slug":"user-auth","type":"feature","path":"...","title":"User Authentication","status":"approved"}
]

Filter by status

./query.sh --type feature --filter-status approved speclan

Find requirements for a feature

./query.sh --type requirement --parent F-1049 speclan

Find change-requests for a requirement

./query.sh --type change-request --parent R-2046 speclan

Combine filters

./query.sh --type requirement --parent F-1049 --filter-status approved --full speclan

Query all entity types

./query.sh --type all speclan

Query Modes

Fast Mode (Default)

Only parses filenames, no file content read:

• Extracts ID and slug from filename pattern
• Infers type from ID prefix
• Fastest for simple listing

Activated when: No --full, --filter-status, or --parent flags

Full Mode (Frontmatter Read)

Reads YAML frontmatter when needed:

• Extract title, status from frontmatter
• Required for filtering or full output

Activated when: --full, --filter-status, or --parent specified

JSON Output Schema

Minimal (fast mode)

{
  "id": "F-1049",
  "slug": "pet-management",
  "type": "feature",
  "path": "speclan/features/F-1049-pet-management/F-1049-pet-management.md"
}

Full (with --full flag)

{
  "id": "F-1049",
  "slug": "pet-management",
  "type": "feature",
  "path": "speclan/...",
  "title": "Pet Management",
  "status": "draft"
}

Parent Filtering

The --parent flag checks multiple locations:

1. Structural parent - ID appears in file path (e.g., F-1049-slug/requirements/R-2046-slug/)
2. Frontmatter fields - feature:, requirement:, parentId:
3. Array fields - Goals array (- G-123)

Integration Examples

In sync-from-session Command

# Index existing features
FEATURES_JSON=$("${CLAUDE_PLUGIN_ROOT}/skills/speclan-query/scripts/query.sh" --type feature --full speclan)

# Check if feature exists
if echo "$FEATURES_JSON" | grep -q '"id":"F-1049"'; then
  echo "Feature exists"
fi

# Get editable features (not locked)
EDITABLE=$("${CLAUDE_PLUGIN_ROOT}/skills/speclan-query/scripts/query.sh" --type feature --filter-status draft speclan)

Extract specific fields with grep

# Get all feature IDs
./query.sh --type feature speclan | grep -oE '"id":"[^"]+"' | cut -d'"' -f4

# Get all paths
./query.sh --type feature speclan | grep -oE '"path":"[^"]+"' | cut -d'"' -f4

# Count entities
./query.sh --type requirement speclan | grep -c '"id"'

Process each entity

./query.sh --type feature --full speclan | grep -oE '"id":"[^"]+"' | cut -d'"' -f4 | while read -r fid; do
  echo "Processing feature: $fid"
  req_count=$(./query.sh --type requirement --parent "$fid" speclan | grep -c '"id"' || echo 0)
  echo "  Requirements: $req_count"
done

Status Reference

For the full status lifecycle and editability rules, consult the speclan-format skill. Key point: statuses draft, review, approved are editable; in-development, under-test, released require Change Requests; deprecated is permanently frozen.

Error Handling

Scenario	Behavior
Missing speclan dir	Error message, exit 1
Invalid entity type	Error message, exit 1
No matches found	Empty JSON array [], exit 0
Malformed filename	Skipped silently
Template files	Skipped automatically
Archived files	Skipped automatically

Performance Notes

• Fast mode: ~50ms for 100 features (filename parsing only)
• Full mode: ~500ms for 100 features (frontmatter reads)
• No caching between queries
• No depth limits on recursive search
• Files in /templates/ and /_archived/ are excluded