Specs Directory

This directory contains feature specifications for the A.R.C. CLI project.

🚨 Important: Architecture Analysis & Patterns Available

After completing Feature 005 (Animations & Rich UI), a comprehensive architectural analysis identified critical technical debt and established industry-standard patterns for future development.

For New Specs (006+):

MUST follow architectural patterns defined in .specify/memory/patterns.md:

✅ Factory Pattern (Dependency Injection)
✅ XDG Base Directory (Config/Data/State separation)
✅ Repository Pattern (Domain-driven storage)
✅ Middleware/UI Service (Centralized UI rendering)

Resources:

Architecture Analysis - Detailed analysis of 7 critical issues
Industry Patterns - How kubectl, gh, docker solve these problems
Refactoring Summary - Quick reference guide
Patterns Checklist - Code review checklist

For Existing Specs (001-005):

Grandfathered - Not required to follow patterns immediately, but recommended during refactoring:

Spec 001: Initial Setup
Spec 002: State Management
Spec 003: Test Infrastructure
Spec 004: Interactive UI Enhancements
Spec 005: Animations & Rich UI

Proposed Refactoring Specs (006-011): Architecture improvements to align with patterns

Structure

Each feature has its own directory with the following structure:

specs/
├── 001-initial-setup/
│   ├── spec.md          # Feature specification (user stories, requirements)
│   ├── plan.md          # Implementation plan (tech context, constitution check)
│   └── tasks.md         # Detailed task breakdown
├── 002-state-management/
│   ├── spec.md
│   ├── plan.md
│   └── tasks.md
├── 003-test-infrastructure/
│   ├── spec.md
│   ├── plan.md
│   ├── research.md      # Research findings
│   └── tasks.md
├── 004-interactive-ui-enhancements/
│   ├── spec.md          # Feature specification
│   ├── plan.md          # Implementation plan
│   ├── research.md      # Research findings
│   ├── data-model.md    # Entity definitions
│   ├── quickstart.md    # Developer guide
│   ├── contracts/       # API contracts
│   │   └── components.md
│   └── tasks.md         # Task breakdown
└── ...

Note: Features 003+ include additional documentation artifacts from the enhanced speckit.plan workflow.

Feature Naming Convention (Updated 2025-12-21)

Unified Naming: Spec Folder = Branch Name

Format: {sequence}-{feature-name}

Examples:

Spec folder: 001-initial-setup → Branch: 001-initial-setup
Spec folder: 002-state-management → Branch: 002-state-management
Spec folder: 003-test-infrastructure → Branch: 003-test-infrastructure

Why This Change?

Old approach (deprecated):

Spec folders used feature sequence (001, 002)
Branch names used PR numbers (007, 014, 018)
Problem: PR numbers jump when features merge out of order
Result: Hard to track folder-to-branch mapping

New approach (current):

Spec folders use sequential numbering (001, 002, 003, 004...)
Branch names match spec folder names exactly
Benefit: Single source of truth, easy tracking, no confusion

See .specify/config.yaml for configuration details.

Feature Mapping

Sequence	Directory	Branch	Status	Notes
001	`001-initial-setup`	`001-initial-setup`	✅ Complete	Initial project setup
002	`002-state-management`	`002-state-management`	✅ Complete	State management system
003	`003-test-infrastructure`	`003-test-infrastructure`	✅ Complete	Formerly 014-test-infrastructure
004	`004-interactive-ui-enhancements`	`004-interactive-ui-enhancements`	✅ Complete	Formerly 018-interactive-ui-enhancements
005	`005-animations-rich-ui`	`005-animations-rich-ui`	✅ Complete	Animations and rich UI components
006	`006-stabilize-base`	`006-stabilize-base`	✅ Complete	Codebase stabilization and refactoring
007	`007-init-wizard`	`007-init-wizard`	✅ Complete	Interactive initialization wizard
008	`008-workspace-config`	`008-workspace-config`	✅ Complete	Workspace configuration system
009	`009-service-catalog`	`009-service-catalog`	✅ Complete	Service catalog and discovery
010	`010-codebase-cleanup-and`	`010-codebase-cleanup-and`	✅ Complete	Codebase cleanup and optimization
011	`011-workspace-orchestration-deep`	`011-workspace-orchestration-deep`	✅ Complete	Deep workspace orchestration
012	`012-ui-error-component`	`012-ui-error-component`	✅ Complete	UI error handling components
013	`013-profile-tiers`	`013-profile-tiers`	⚠️ In Progress	Profile-based tier system (infrastructure complete, integration pending)

Document Templates

Core Documents (All Features)

spec.md

Contains the feature specification including:

User stories with priorities (P1, P2, P3...)
Functional requirements (FR-001, FR-002...)
Non-functional requirements (NFR-001, NFR-002...)
Edge cases and constraints
Success criteria
Acceptance scenarios

plan.md

Contains the implementation plan including:

Summary
Technical context (language, dependencies, performance goals)
Constitution compliance check (v1.1.0)
Project structure (file layout)
Implementation phases (Phase 0, 1, 2)
Re-evaluation after design

tasks.md

Contains the detailed task breakdown including:

Task list organized by user story (- [ ] T001 [P?] [Story?] Description)
Setup, Foundational, User Story, and Polish phases
Parallel execution opportunities ([P] marker)
Dependencies and execution order
Implementation strategies (MVP first, incremental, parallel)
Time estimates and validation checklist

Additional Documents (Enhanced Workflow - Feature 014+)

research.md (Phase 0 Output)

Contains research findings including:

Investigation topics (7+ research tasks)
Decisions made with rationale
Alternatives considered
Best practices identified
Open questions resolved

data-model.md (Phase 1 Output)

Contains entity definitions including:

Core entities with fields and validation rules
Relationships and state transitions
Configuration file structures
Performance considerations
Caching strategies

quickstart.md (Phase 1 Output)

Contains developer guide including:

Installation and setup
Quick examples for all features
Configuration options
Environment variables
Command reference
Testing checklist and troubleshooting

contracts/ (Phase 1 Output)

Contains API contracts including:

Component interfaces
Usage examples
Error handling patterns
Performance contracts
Testing contracts
Backward compatibility notes

Workflow

1. Create New Feature Spec

# Use the helper script to create branch and spec directory
.specify/scripts/bash/create-new-feature.sh "Interactive UI Enhancements"

# This automatically:
# 1. Determines next PR number
# 2. Creates branch: {pr-number}-{feature-name}
# 3. Creates spec directory: specs/{pr-number}-{feature-name}
# 4. Creates spec.md from template

2. Write Specification

Use the speckit commands to generate comprehensive documentation:

# Step 1: Fill out spec.md with user stories and requirements
# Edit: specs/{pr-number}-{feature-name}/spec.md

# Step 2: Run speckit.plan to generate design documents
# This creates: plan.md, research.md, data-model.md, contracts/, quickstart.md
# (Use AI assistant with /speckit.plan mode)

# Step 3: Run speckit.tasks to generate task breakdown
# This creates: tasks.md with 92+ tasks organized by user story
# (Use AI assistant with /speckit.tasks mode)

Enhanced Workflow Outputs:

spec.md - What we're building (user stories, requirements)
plan.md - How we'll build it (tech context, constitution check)
research.md - Phase 0: Research findings and decisions
data-model.md - Phase 1: Entity definitions
contracts/ - Phase 1: API interfaces
quickstart.md - Phase 1: Developer guide
tasks.md - Phase 2: Detailed task breakdown

3. Implement Feature

Follow the tasks in tasks.md, checking off items as you complete them:

# Tasks are organized by phase:
# Phase 1: Setup (5 tasks)
# Phase 2: Foundational (24 tasks) - BLOCKS all user stories
# Phase 3-N: User Stories (P1, P2, P3 priorities)
# Final Phase: Polish & cross-cutting

# Check off tasks as completed:
- [x] T001 Add dependencies to go.mod
- [x] T002 Create directory structure
- [ ] T003 Implement terminal detection

4. Create Pull Request

# Push branch (branch name matches spec folder name)
git push origin 004-interactive-ui-enhancements

# Create PR
gh pr create \
  --title "004: Interactive UI Enhancements" \
  --body "Implements Charmbracelet ecosystem integration. See specs/004-interactive-ui-enhancements/"

5. Update Status

After PR is merged, update the spec files:

**Status**: ✅ Complete
**Merged**: PR #18 (2025-12-21)

Current Features

001: Initial Setup (✅ Complete)

Directory: specs/001-initial-setup/
Branch: 001-initial-setup
Merged: 2025-12-19
Description: CLI foundation, banner, help screen, styling system, Go 1.24 setup

002: State Management (✅ Complete)

Directory: specs/002-state-management/
Branch: 002-state-management
Merged: 2025-12-20
Description: Persistent state tracking, history management, state/history commands

003: Test Infrastructure (✅ Complete)

Directory: specs/003-test-infrastructure/
Branch: 003-test-infrastructure
Merged: 2025-12-20
Description: Comprehensive test setup with testify, test utilities, mocks, and coverage tooling
Note: Formerly numbered 014, renumbered for sequential consistency

004: Interactive UI Enhancements (✅ Complete)

Directory: specs/004-interactive-ui-enhancements/
Branch: 004-interactive-ui-enhancements
Merged: 2025-12-21
Status: All 116 tasks complete, ready for production
Description: Charmbracelet ecosystem integration (Bubble Tea, Harmonica, Lipgloss, Charm Log) for smooth animations, interactive components, and structured logging
Note: Formerly numbered 018, renumbered for sequential consistency
Documentation:
- ✅ spec.md (7 user stories, 45 FRs, 20 NFRs)
- ✅ plan.md (implementation plan with constitution check)
- ✅ research.md (7 research decisions)
- ✅ data-model.md (7 core entities)
- ✅ contracts/components.md (7 component interfaces)
- ✅ quickstart.md (developer guide)
- ✅ tasks.md (116 tasks complete, all passing tests)

References

Branching Convention - Branch naming rules
Development Guide - Development workflow
Release System - Release process

Tools

Create New Branch

./scripts/new-branch.sh

Automatically:

Determines next PR number
Prompts for feature name
Creates branch with PR-based naming
Provides next steps

List All Specs

ls -la specs/

Find Spec by PR Number

# Find which spec corresponds to PR #7
git branch -a | grep "007-"
# Output: 007-state-management

# Spec directory is: specs/002-state-management/

Best Practices

One feature per spec directory - Keep features focused and independently deliverable
Use the PR-number-based branching convention - Branch names match PR numbers for traceability
Generate comprehensive documentation - Use speckit.plan and speckit.tasks for thorough planning
Keep specs updated - Mark tasks complete as you go ([x] instead of [ ])
Link PRs to specs - Reference spec directory in PR description
Archive completed specs - Don't delete, they're valuable documentation
Document decisions in research.md - Record why, not just what
Organize tasks by user story - Enable independent implementation and testing
Validate each user story independently - Test at each checkpoint before moving on
Consider MVP scope first - Implement P1 features before P2/P3

Questions?

See BRANCHING_CONVENTION.md or ask a maintainer.

Uh oh!

FilesExpand file tree

README.md

Latest commit

History