From 5da66083111ae1ea5f586bbe2965ee220260cf6d Mon Sep 17 00:00:00 2001 From: impactaly Date: Sun, 28 Dec 2025 17:01:58 +0900 Subject: [PATCH] Remove openspec files --- .claude/commands/openspec/apply.md | 23 - .claude/commands/openspec/archive.md | 21 - .claude/commands/openspec/proposal.md | 27 -- .cursor/commands/openspec-apply.md | 23 - .cursor/commands/openspec-archive.md | 21 - .cursor/commands/openspec-proposal.md | 27 -- AGENTS.md | 18 - CLAUDE.md | 129 ----- openspec/AGENTS.md | 456 ------------------ .../proposal.md | 19 - .../specs/nix-build/spec.md | 13 - .../tasks.md | 27 -- .../remove-ai-tools-package/proposal.md | 16 - .../specs/nix-flake/spec.md | 12 - .../changes/remove-ai-tools-package/tasks.md | 12 - openspec/project.md | 107 ---- 16 files changed, 951 deletions(-) delete mode 100644 .claude/commands/openspec/apply.md delete mode 100644 .claude/commands/openspec/archive.md delete mode 100644 .claude/commands/openspec/proposal.md delete mode 100644 .cursor/commands/openspec-apply.md delete mode 100644 .cursor/commands/openspec-archive.md delete mode 100644 .cursor/commands/openspec-proposal.md delete mode 100644 AGENTS.md delete mode 100644 CLAUDE.md delete mode 100644 openspec/AGENTS.md delete mode 100644 openspec/changes/archive/2025-12-14-remove-shelffiles-env-generator/proposal.md delete mode 100644 openspec/changes/archive/2025-12-14-remove-shelffiles-env-generator/specs/nix-build/spec.md delete mode 100644 openspec/changes/archive/2025-12-14-remove-shelffiles-env-generator/tasks.md delete mode 100644 openspec/changes/remove-ai-tools-package/proposal.md delete mode 100644 openspec/changes/remove-ai-tools-package/specs/nix-flake/spec.md delete mode 100644 openspec/changes/remove-ai-tools-package/tasks.md delete mode 100644 openspec/project.md diff --git a/.claude/commands/openspec/apply.md b/.claude/commands/openspec/apply.md deleted file mode 100644 index a36fd96..0000000 --- a/.claude/commands/openspec/apply.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -name: OpenSpec: Apply -description: Implement an approved OpenSpec change and keep tasks in sync. -category: OpenSpec -tags: [openspec, apply] ---- - -**Guardrails** -- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required. -- Keep changes tightly scoped to the requested outcome. -- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications. - -**Steps** -Track these steps as TODOs and complete them one by one. -1. Read `changes//proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria. -2. Work through tasks sequentially, keeping edits minimal and focused on the requested change. -3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished. -4. Update the checklist after all work is done so each task is marked `- [x]` and reflects reality. -5. Reference `openspec list` or `openspec show ` when additional context is required. - -**Reference** -- Use `openspec show --json --deltas-only` if you need additional context from the proposal while implementing. - diff --git a/.claude/commands/openspec/archive.md b/.claude/commands/openspec/archive.md deleted file mode 100644 index 511b424..0000000 --- a/.claude/commands/openspec/archive.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -name: OpenSpec: Archive -description: Archive a deployed OpenSpec change and update specs. -category: OpenSpec -tags: [openspec, archive] ---- - -**Guardrails** -- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required. -- Keep changes tightly scoped to the requested outcome. -- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications. - -**Steps** -1. Identify the requested change ID (via the prompt or `openspec list`). -2. Run `openspec archive --yes` to let the CLI move the change and apply spec updates without prompts (use `--skip-specs` only for tooling-only work). -3. Review the command output to confirm the target specs were updated and the change landed in `changes/archive/`. -4. Validate with `openspec validate --strict` and inspect with `openspec show ` if anything looks off. - -**Reference** -- Inspect refreshed specs with `openspec list --specs` and address any validation issues before handing off. - diff --git a/.claude/commands/openspec/proposal.md b/.claude/commands/openspec/proposal.md deleted file mode 100644 index f4c1c97..0000000 --- a/.claude/commands/openspec/proposal.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -name: OpenSpec: Proposal -description: Scaffold a new OpenSpec change and validate strictly. -category: OpenSpec -tags: [openspec, change] ---- - -**Guardrails** -- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required. -- Keep changes tightly scoped to the requested outcome. -- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications. -- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files. - -**Steps** -1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification. -2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes//`. -3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing. -4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs. -5. Draft spec deltas in `changes//specs//spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant. -6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work. -7. Validate with `openspec validate --strict` and resolve every issue before sharing the proposal. - -**Reference** -- Use `openspec show --json --deltas-only` or `openspec show --type spec` to inspect details when validation fails. -- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones. -- Explore the codebase with `rg `, `ls`, or direct file reads so proposals align with current implementation realities. - diff --git a/.cursor/commands/openspec-apply.md b/.cursor/commands/openspec-apply.md deleted file mode 100644 index 99a9148..0000000 --- a/.cursor/commands/openspec-apply.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -name: /openspec-apply -id: openspec-apply -category: OpenSpec -description: Implement an approved OpenSpec change and keep tasks in sync. ---- - -**Guardrails** -- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required. -- Keep changes tightly scoped to the requested outcome. -- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications. - -**Steps** -Track these steps as TODOs and complete them one by one. -1. Read `changes//proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria. -2. Work through tasks sequentially, keeping edits minimal and focused on the requested change. -3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished. -4. Update the checklist after all work is done so each task is marked `- [x]` and reflects reality. -5. Reference `openspec list` or `openspec show ` when additional context is required. - -**Reference** -- Use `openspec show --json --deltas-only` if you need additional context from the proposal while implementing. - diff --git a/.cursor/commands/openspec-archive.md b/.cursor/commands/openspec-archive.md deleted file mode 100644 index 1d08151..0000000 --- a/.cursor/commands/openspec-archive.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -name: /openspec-archive -id: openspec-archive -category: OpenSpec -description: Archive a deployed OpenSpec change and update specs. ---- - -**Guardrails** -- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required. -- Keep changes tightly scoped to the requested outcome. -- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications. - -**Steps** -1. Identify the requested change ID (via the prompt or `openspec list`). -2. Run `openspec archive --yes` to let the CLI move the change and apply spec updates without prompts (use `--skip-specs` only for tooling-only work). -3. Review the command output to confirm the target specs were updated and the change landed in `changes/archive/`. -4. Validate with `openspec validate --strict` and inspect with `openspec show ` if anything looks off. - -**Reference** -- Inspect refreshed specs with `openspec list --specs` and address any validation issues before handing off. - diff --git a/.cursor/commands/openspec-proposal.md b/.cursor/commands/openspec-proposal.md deleted file mode 100644 index 2d7ed7e..0000000 --- a/.cursor/commands/openspec-proposal.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -name: /openspec-proposal -id: openspec-proposal -category: OpenSpec -description: Scaffold a new OpenSpec change and validate strictly. ---- - -**Guardrails** -- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required. -- Keep changes tightly scoped to the requested outcome. -- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications. -- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files. - -**Steps** -1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification. -2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes//`. -3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing. -4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs. -5. Draft spec deltas in `changes//specs//spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant. -6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work. -7. Validate with `openspec validate --strict` and resolve every issue before sharing the proposal. - -**Reference** -- Use `openspec show --json --deltas-only` or `openspec show --type spec` to inspect details when validation fails. -- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones. -- Explore the codebase with `rg `, `ls`, or direct file reads so proposals align with current implementation realities. - diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 0669699..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,18 +0,0 @@ - -# OpenSpec Instructions - -These instructions are for AI assistants working in this project. - -Always open `@/openspec/AGENTS.md` when the request: -- Mentions planning or proposals (words like proposal, spec, change, plan) -- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work -- Sounds ambiguous and you need the authoritative spec before coding - -Use `@/openspec/AGENTS.md` to learn: -- How to create and apply change proposals -- Spec format and conventions -- Project structure and guidelines - -Keep this managed block so 'openspec update' can refresh the instructions. - - \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 6299709..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,129 +0,0 @@ - -# OpenSpec Instructions - -These instructions are for AI assistants working in this project. - -Always open `@/openspec/AGENTS.md` when the request: -- Mentions planning or proposals (words like proposal, spec, change, plan) -- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work -- Sounds ambiguous and you need the authoritative spec before coding - -Use `@/openspec/AGENTS.md` to learn: -- How to create and apply change proposals -- Spec format and conventions -- Project structure and guidelines - -Keep this managed block so 'openspec update' can refresh the instructions. - - - -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Development Commands - -### Setup and Build -```bash -# Setup development environment (uses argc for CLI parsing) -./setup.sh [--no-root] - -# Build packages using Nix -nix build - -# Build in Docker environment (fallback when Nix unavailable) -./utils/build_nix_in_docker.sh -``` - -### Testing -```bash -# Run complete test suite via Docker -docker build -f test/Dockerfile . - -# Run individual shell tests (requires BATS) -bats test/test/bashrc_load.bats -bats test/test/zshrc_load.bats -bats test/test/fishrc_load.bats -``` - -### Environment Usage -```bash -# Enter shell-specific environments -./entrypoint/bash # Bash with XDG config loading -./entrypoint/zsh # Zsh with ZDOTDIR configuration -./entrypoint/fish # Fish with config.fish loading -``` - -### Package Management -```bash -# Edit packages.nix to modify available packages -# Then rebuild environment -nix build -``` - -## Architecture Overview - -Shelffiles integrates three core systems: - -### 1. Nix Flakes Layer -- `flake.nix`: Defines multi-architecture package environment -- `packages.nix`: User-customizable package list -- Creates reproducible `buildEnv` across Linux/macOS on x86_64/aarch64 - -### 2. XDG Environment Management -- `entrypoint/env.sh`: Sets XDG base directory variables pointing to repository subdirectories -- Uses `${PATH_ID}` (user/group-specific) to prevent conflicts between users -- Automatically creates `cache/`, `share/`, `state/` directories as needed - -### 3. Shell Integration Layer -- `entrypoint/{bash,zsh,fish}`: Shell-specific launchers -- Each sets appropriate shell variables (ZDOTDIR for zsh, HISTFILE for bash) -- Falls back to `launch_in_bwrap.sh` containerized execution when Nix packages unavailable - -### Containerization Fallback -- `launch_in_bwrap.sh`: Uses bubblewrap to create isolated environment -- Mounts repository's `/nix` directory into container for package access -- Provides security and portability when direct Nix execution not available - -## Testing Infrastructure - -### BATS Framework -- Tests verify each shell correctly loads configurations from `config/` directories -- Test configs set environment variables (`SHELFFILES_*_TEST="loaded"`) to verify loading -- Docker-based CI ensures reproducible testing environment - -### CI/CD Workflows -- **Docker Build**: Tests complete setup in clean environment with layer caching -- **Lint**: Pre-commit hooks (shellcheck, trailing whitespace, YAML validation, hadolint) -- **Argc Verification**: Ensures `setup.sh` stays synchronized with argc generation -- **Claude Code**: AI assistance triggered by @claude mentions - -## Development Considerations - -### Argc Integration -- `setup.sh` generated by argc CLI framework - do not manually edit argc-generated sections -- Regenerate with: `argc --argc-build setup.sh > setup.sh` -- CI enforces this requirement via checksum verification - -### Git Integration Features -- `example/config/git/`: Contains filter configuration to exclude "shelffiles" lines from devcontainer.json commits -- Enables local devcontainer customization without affecting repository - -### XDG Compliance -- Configuration files automatically discovered by applications using XDG specification -- User-specific paths prevent conflicts in multi-user environments -- Standard directory hierarchy: `config/`, `cache/`, `share/`, `state/` - -## Build Artifacts and Dependencies - -### Key Dependencies -- **Nix** with flakes support (primary dependency) -- **Docker** (testing and fallback builds) -- **Bubblewrap** (containerized execution) -- **Argc** (CLI argument parsing generation) - -### Generated Artifacts -- `result/`: Nix build output symlink -- `result_docker/`: Docker-based build output -- `cache/`, `share/`, `state/`: XDG directories (git-ignored) -- `/nix`: Copied Nix store for containerized environments (git-ignored) \ No newline at end of file diff --git a/openspec/AGENTS.md b/openspec/AGENTS.md deleted file mode 100644 index d84d6df..0000000 --- a/openspec/AGENTS.md +++ /dev/null @@ -1,456 +0,0 @@ -# OpenSpec Instructions - -Instructions for AI coding assistants using OpenSpec for spec-driven development. - -## TL;DR Quick Checklist - -- Search existing work: `openspec spec list --long`, `openspec list` (use `rg` only for full-text search) -- Decide scope: new capability vs modify existing capability -- Pick a unique `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`, `refactor-`) -- Scaffold: `proposal.md`, `tasks.md`, `design.md` (only if needed), and delta specs per affected capability -- Write deltas: use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`; include at least one `#### Scenario:` per requirement -- Validate: `openspec validate [change-id] --strict` and fix issues -- Request approval: Do not start implementation until proposal is approved - -## Three-Stage Workflow - -### Stage 1: Creating Changes -Create proposal when you need to: -- Add features or functionality -- Make breaking changes (API, schema) -- Change architecture or patterns -- Optimize performance (changes behavior) -- Update security patterns - -Triggers (examples): -- "Help me create a change proposal" -- "Help me plan a change" -- "Help me create a proposal" -- "I want to create a spec proposal" -- "I want to create a spec" - -Loose matching guidance: -- Contains one of: `proposal`, `change`, `spec` -- With one of: `create`, `plan`, `make`, `start`, `help` - -Skip proposal for: -- Bug fixes (restore intended behavior) -- Typos, formatting, comments -- Dependency updates (non-breaking) -- Configuration changes -- Tests for existing behavior - -**Workflow** -1. Review `openspec/project.md`, `openspec list`, and `openspec list --specs` to understand current context. -2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas under `openspec/changes//`. -3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement. -4. Run `openspec validate --strict` and resolve any issues before sharing the proposal. - -### Stage 2: Implementing Changes -Track these steps as TODOs and complete them one by one. -1. **Read proposal.md** - Understand what's being built -2. **Read design.md** (if exists) - Review technical decisions -3. **Read tasks.md** - Get implementation checklist -4. **Implement tasks sequentially** - Complete in order -5. **Confirm completion** - Ensure every item in `tasks.md` is finished before updating statuses -6. **Update checklist** - After all work is done, set every task to `- [x]` so the list reflects reality -7. **Approval gate** - Do not start implementation until the proposal is reviewed and approved - -### Stage 3: Archiving Changes -After deployment, create separate PR to: -- Move `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/` -- Update `specs/` if capabilities changed -- Use `openspec archive [change] --skip-specs --yes` for tooling-only changes -- Run `openspec validate --strict` to confirm the archived change passes checks - -## Before Any Task - -**Context Checklist:** -- [ ] Read relevant specs in `specs/[capability]/spec.md` -- [ ] Check pending changes in `changes/` for conflicts -- [ ] Read `openspec/project.md` for conventions -- [ ] Run `openspec list` to see active changes -- [ ] Run `openspec list --specs` to see existing capabilities - -**Before Creating Specs:** -- Always check if capability already exists -- Prefer modifying existing specs over creating duplicates -- Use `openspec show [spec]` to review current state -- If request is ambiguous, ask 1–2 clarifying questions before scaffolding - -### Search Guidance -- Enumerate specs: `openspec spec list --long` (or `--json` for scripts) -- Enumerate changes: `openspec list` (or `openspec change list --json` - deprecated but available) -- Show details: - - Spec: `openspec show --type spec` (use `--json` for filters) - - Change: `openspec show --json --deltas-only` -- Full-text search (use ripgrep): `rg -n "Requirement:|Scenario:" openspec/specs` - -## Quick Start - -### CLI Commands - -```bash -# Essential commands -openspec list # List active changes -openspec list --specs # List specifications -openspec show [item] # Display change or spec -openspec diff [change] # Show spec differences -openspec validate [item] # Validate changes or specs -openspec archive [change] [--yes|-y] # Archive after deployment (add --yes for non-interactive runs) - -# Project management -openspec init [path] # Initialize OpenSpec -openspec update [path] # Update instruction files - -# Interactive mode -openspec show # Prompts for selection -openspec validate # Bulk validation mode - -# Debugging -openspec show [change] --json --deltas-only -openspec validate [change] --strict -``` - -### Command Flags - -- `--json` - Machine-readable output -- `--type change|spec` - Disambiguate items -- `--strict` - Comprehensive validation -- `--no-interactive` - Disable prompts -- `--skip-specs` - Archive without spec updates -- `--yes`/`-y` - Skip confirmation prompts (non-interactive archive) - -## Directory Structure - -``` -openspec/ -├── project.md # Project conventions -├── specs/ # Current truth - what IS built -│ └── [capability]/ # Single focused capability -│ ├── spec.md # Requirements and scenarios -│ └── design.md # Technical patterns -├── changes/ # Proposals - what SHOULD change -│ ├── [change-name]/ -│ │ ├── proposal.md # Why, what, impact -│ │ ├── tasks.md # Implementation checklist -│ │ ├── design.md # Technical decisions (optional; see criteria) -│ │ └── specs/ # Delta changes -│ │ └── [capability]/ -│ │ └── spec.md # ADDED/MODIFIED/REMOVED -│ └── archive/ # Completed changes -``` - -## Creating Change Proposals - -### Decision Tree - -``` -New request? -├─ Bug fix restoring spec behavior? → Fix directly -├─ Typo/format/comment? → Fix directly -├─ New feature/capability? → Create proposal -├─ Breaking change? → Create proposal -├─ Architecture change? → Create proposal -└─ Unclear? → Create proposal (safer) -``` - -### Proposal Structure - -1. **Create directory:** `changes/[change-id]/` (kebab-case, verb-led, unique) - -2. **Write proposal.md:** -```markdown -## Why -[1-2 sentences on problem/opportunity] - -## What Changes -- [Bullet list of changes] -- [Mark breaking changes with **BREAKING**] - -## Impact -- Affected specs: [list capabilities] -- Affected code: [key files/systems] -``` - -3. **Create spec deltas:** `specs/[capability]/spec.md` -```markdown -## ADDED Requirements -### Requirement: New Feature -The system SHALL provide... - -#### Scenario: Success case -- **WHEN** user performs action -- **THEN** expected result - -## MODIFIED Requirements -### Requirement: Existing Feature -[Complete modified requirement] - -## REMOVED Requirements -### Requirement: Old Feature -**Reason**: [Why removing] -**Migration**: [How to handle] -``` -If multiple capabilities are affected, create multiple delta files under `changes/[change-id]/specs//spec.md`—one per capability. - -4. **Create tasks.md:** -```markdown -## 1. Implementation -- [ ] 1.1 Create database schema -- [ ] 1.2 Implement API endpoint -- [ ] 1.3 Add frontend component -- [ ] 1.4 Write tests -``` - -5. **Create design.md when needed:** -Create `design.md` if any of the following apply; otherwise omit it: -- Cross-cutting change (multiple services/modules) or a new architectural pattern -- New external dependency or significant data model changes -- Security, performance, or migration complexity -- Ambiguity that benefits from technical decisions before coding - -Minimal `design.md` skeleton: -```markdown -## Context -[Background, constraints, stakeholders] - -## Goals / Non-Goals -- Goals: [...] -- Non-Goals: [...] - -## Decisions -- Decision: [What and why] -- Alternatives considered: [Options + rationale] - -## Risks / Trade-offs -- [Risk] → Mitigation - -## Migration Plan -[Steps, rollback] - -## Open Questions -- [...] -``` - -## Spec File Format - -### Critical: Scenario Formatting - -**CORRECT** (use #### headers): -```markdown -#### Scenario: User login success -- **WHEN** valid credentials provided -- **THEN** return JWT token -``` - -**WRONG** (don't use bullets or bold): -```markdown -- **Scenario: User login** ❌ -**Scenario**: User login ❌ -### Scenario: User login ❌ -``` - -Every requirement MUST have at least one scenario. - -### Requirement Wording -- Use SHALL/MUST for normative requirements (avoid should/may unless intentionally non-normative) - -### Delta Operations - -- `## ADDED Requirements` - New capabilities -- `## MODIFIED Requirements` - Changed behavior -- `## REMOVED Requirements` - Deprecated features -- `## RENAMED Requirements` - Name changes - -Headers matched with `trim(header)` - whitespace ignored. - -#### When to use ADDED vs MODIFIED -- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding "Slash Command Configuration") rather than altering the semantics of an existing requirement. -- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details. -- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name. - -Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead. - -Authoring a MODIFIED requirement correctly: -1) Locate the existing requirement in `openspec/specs//spec.md`. -2) Copy the entire requirement block (from `### Requirement: ...` through its scenarios). -3) Paste it under `## MODIFIED Requirements` and edit to reflect the new behavior. -4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one `#### Scenario:`. - -Example for RENAMED: -```markdown -## RENAMED Requirements -- FROM: `### Requirement: Login` -- TO: `### Requirement: User Authentication` -``` - -## Troubleshooting - -### Common Errors - -**"Change must have at least one delta"** -- Check `changes/[name]/specs/` exists with .md files -- Verify files have operation prefixes (## ADDED Requirements) - -**"Requirement must have at least one scenario"** -- Check scenarios use `#### Scenario:` format (4 hashtags) -- Don't use bullet points or bold for scenario headers - -**Silent scenario parsing failures** -- Exact format required: `#### Scenario: Name` -- Debug with: `openspec show [change] --json --deltas-only` - -### Validation Tips - -```bash -# Always use strict mode for comprehensive checks -openspec validate [change] --strict - -# Debug delta parsing -openspec show [change] --json | jq '.deltas' - -# Check specific requirement -openspec show [spec] --json -r 1 -``` - -## Happy Path Script - -```bash -# 1) Explore current state -openspec spec list --long -openspec list -# Optional full-text search: -# rg -n "Requirement:|Scenario:" openspec/specs -# rg -n "^#|Requirement:" openspec/changes - -# 2) Choose change id and scaffold -CHANGE=add-two-factor-auth -mkdir -p openspec/changes/$CHANGE/{specs/auth} -printf "## Why\n...\n\n## What Changes\n- ...\n\n## Impact\n- ...\n" > openspec/changes/$CHANGE/proposal.md -printf "## 1. Implementation\n- [ ] 1.1 ...\n" > openspec/changes/$CHANGE/tasks.md - -# 3) Add deltas (example) -cat > openspec/changes/$CHANGE/specs/auth/spec.md << 'EOF' -## ADDED Requirements -### Requirement: Two-Factor Authentication -Users MUST provide a second factor during login. - -#### Scenario: OTP required -- **WHEN** valid credentials are provided -- **THEN** an OTP challenge is required -EOF - -# 4) Validate -openspec validate $CHANGE --strict -``` - -## Multi-Capability Example - -``` -openspec/changes/add-2fa-notify/ -├── proposal.md -├── tasks.md -└── specs/ - ├── auth/ - │ └── spec.md # ADDED: Two-Factor Authentication - └── notifications/ - └── spec.md # ADDED: OTP email notification -``` - -auth/spec.md -```markdown -## ADDED Requirements -### Requirement: Two-Factor Authentication -... -``` - -notifications/spec.md -```markdown -## ADDED Requirements -### Requirement: OTP Email Notification -... -``` - -## Best Practices - -### Simplicity First -- Default to <100 lines of new code -- Single-file implementations until proven insufficient -- Avoid frameworks without clear justification -- Choose boring, proven patterns - -### Complexity Triggers -Only add complexity with: -- Performance data showing current solution too slow -- Concrete scale requirements (>1000 users, >100MB data) -- Multiple proven use cases requiring abstraction - -### Clear References -- Use `file.ts:42` format for code locations -- Reference specs as `specs/auth/spec.md` -- Link related changes and PRs - -### Capability Naming -- Use verb-noun: `user-auth`, `payment-capture` -- Single purpose per capability -- 10-minute understandability rule -- Split if description needs "AND" - -### Change ID Naming -- Use kebab-case, short and descriptive: `add-two-factor-auth` -- Prefer verb-led prefixes: `add-`, `update-`, `remove-`, `refactor-` -- Ensure uniqueness; if taken, append `-2`, `-3`, etc. - -## Tool Selection Guide - -| Task | Tool | Why | -|------|------|-----| -| Find files by pattern | Glob | Fast pattern matching | -| Search code content | Grep | Optimized regex search | -| Read specific files | Read | Direct file access | -| Explore unknown scope | Task | Multi-step investigation | - -## Error Recovery - -### Change Conflicts -1. Run `openspec list` to see active changes -2. Check for overlapping specs -3. Coordinate with change owners -4. Consider combining proposals - -### Validation Failures -1. Run with `--strict` flag -2. Check JSON output for details -3. Verify spec file format -4. Ensure scenarios properly formatted - -### Missing Context -1. Read project.md first -2. Check related specs -3. Review recent archives -4. Ask for clarification - -## Quick Reference - -### Stage Indicators -- `changes/` - Proposed, not yet built -- `specs/` - Built and deployed -- `archive/` - Completed changes - -### File Purposes -- `proposal.md` - Why and what -- `tasks.md` - Implementation steps -- `design.md` - Technical decisions -- `spec.md` - Requirements and behavior - -### CLI Essentials -```bash -openspec list # What's in progress? -openspec show [item] # View details -openspec diff [change] # What's changing? -openspec validate --strict # Is it correct? -openspec archive [change] [--yes|-y] # Mark complete (add --yes for automation) -``` - -Remember: Specs are truth. Changes are proposals. Keep them in sync. diff --git a/openspec/changes/archive/2025-12-14-remove-shelffiles-env-generator/proposal.md b/openspec/changes/archive/2025-12-14-remove-shelffiles-env-generator/proposal.md deleted file mode 100644 index afdfcf4..0000000 --- a/openspec/changes/archive/2025-12-14-remove-shelffiles-env-generator/proposal.md +++ /dev/null @@ -1,19 +0,0 @@ -## Why - -The automatic environment generation feature (`shelffiles-env-generator`) creates conflicts when users use other package/environment management tools like mise. The automatic detection and generation of package-specific environment variables makes it difficult to correctly manage packages across multiple tools. Removing this feature simplifies the codebase and gives users explicit control over their environment setup. - -## What Changes - -- **BREAKING**: Remove automatic `generated_env.sh` generation from nix build process -- Remove `shelffiles/generate_env.sh` script -- Revert `flake.nix` to simpler `buildEnv` without env generation -- Revert `entrypoint/env.sh` to not source generated environment file -- Revert `entrypoint/bash` to include HISTFILE setup directly -- Revert `entrypoint/zsh` to include ZDOTDIR setup directly (with USER_ZDOTDIR referencing ZDOTDIR) -- Keep `shelffiles/packages/*.sh` files for manual user sourcing - -## Impact - -- Affected specs: nix-build (or shell-integration if exists) -- Affected code: `flake.nix`, `entrypoint/env.sh`, `entrypoint/bash`, `entrypoint/zsh`, `shelffiles/generate_env.sh` -- Users who relied on automatic environment setup should manually source needed files from `shelffiles/packages/` in their `user_env.sh` diff --git a/openspec/changes/archive/2025-12-14-remove-shelffiles-env-generator/specs/nix-build/spec.md b/openspec/changes/archive/2025-12-14-remove-shelffiles-env-generator/specs/nix-build/spec.md deleted file mode 100644 index 2ab22bc..0000000 --- a/openspec/changes/archive/2025-12-14-remove-shelffiles-env-generator/specs/nix-build/spec.md +++ /dev/null @@ -1,13 +0,0 @@ -## REMOVED Requirements - -### Requirement: Automatic Package Environment Generation - -**Reason**: Conflicts with other environment management tools (e.g., mise) and makes package configuration opaque. Users should explicitly configure package-specific environment variables. - -**Migration**: Users who need package-specific environment variables (e.g., HISTFILE, ZDOTDIR, NPM_CONFIG_USERCONFIG) should add them to `user_env.sh` in the repository root. - -#### Scenario: No automatic env generation on build - -- **WHEN** user runs `nix build` -- **THEN** the build SHALL NOT generate `generated_env.sh` -- **AND** the build output SHALL NOT include `shelffiles-env-generator` derivation diff --git a/openspec/changes/archive/2025-12-14-remove-shelffiles-env-generator/tasks.md b/openspec/changes/archive/2025-12-14-remove-shelffiles-env-generator/tasks.md deleted file mode 100644 index 0c89e73..0000000 --- a/openspec/changes/archive/2025-12-14-remove-shelffiles-env-generator/tasks.md +++ /dev/null @@ -1,27 +0,0 @@ -## 1. Revert automatic env generation - -- [x] 1.1 Remove `shelffiles/generate_env.sh` -- [x] 1.2 Revert `flake.nix` to simple buildEnv without env generation -- [x] 1.3 Revert `entrypoint/env.sh` to not source generated environment file -- [x] 1.4 Revert `entrypoint/bash` to include HISTFILE setup directly -- [x] 1.5 Revert `entrypoint/zsh` to include ZDOTDIR setup directly -- [x] 1.6 Fix USER_ZDOTDIR to reference ZDOTDIR variable - -## 2. Keep package environment files - -- [x] 2.1 Keep `shelffiles/packages/*.sh` files for manual user sourcing -- [x] 2.2 Keep `.dockerignore` file - -## 3. Update documentation - -- [x] 3.1 Update `openspec/project.md` to remove references to `generated_env.sh` - -## 4. Verify and test - -- [x] 4.1 Build with `nix build` to ensure the simplified flake works (verified via Docker) -- [x] 4.2 Run test suite via `docker build -f test/Dockerfile .` - -## 5. Commit and create PR - -- [ ] 5.1 Commit the changes with descriptive message -- [ ] 5.2 Create PR with summary of breaking change diff --git a/openspec/changes/remove-ai-tools-package/proposal.md b/openspec/changes/remove-ai-tools-package/proposal.md deleted file mode 100644 index fed807e..0000000 --- a/openspec/changes/remove-ai-tools-package/proposal.md +++ /dev/null @@ -1,16 +0,0 @@ -## Why - -The nix-ai-tools input adds complexity to the flake for little benefit. Alternative tools like mise can handle AI tooling installation better, with simpler configuration and broader ecosystem support. Removing this simplifies maintenance. - -## What Changes - -- **BREAKING**: Remove `nix-ai-tools` input from `flake.nix` -- Simplify `packages.nix` function signature (remove `nix-ai-tools` parameter) -- Simplify `test/packages.nix` function signature (remove `nix-ai-tools` parameter) -- Update `openspec/project.md` documentation to remove nix-ai-tools references - -## Impact - -- Affected specs: None (no specs exist yet for nix-flake) -- Affected code: `flake.nix`, `packages.nix`, `test/packages.nix`, `openspec/project.md` -- Users relying on `nix-ai-tools` packages will need to use alternative installation methods (mise, direct nix package installation, etc.) diff --git a/openspec/changes/remove-ai-tools-package/specs/nix-flake/spec.md b/openspec/changes/remove-ai-tools-package/specs/nix-flake/spec.md deleted file mode 100644 index 371b16d..0000000 --- a/openspec/changes/remove-ai-tools-package/specs/nix-flake/spec.md +++ /dev/null @@ -1,12 +0,0 @@ -## REMOVED Requirements - -### Requirement: nix-ai-tools Integration - -**Reason**: Alternative tools like mise handle AI tooling installation more flexibly with simpler configuration. Maintaining a dedicated flake input adds complexity for minimal benefit. - -**Migration**: Users should use mise, direct nixpkgs packages, or other package managers for AI development tools. - -#### Scenario: User previously using nix-ai-tools - -- **WHEN** user has nix-ai-tools packages in their packages.nix -- **THEN** they must migrate to alternative installation methods (mise, nixpkgs, etc.) diff --git a/openspec/changes/remove-ai-tools-package/tasks.md b/openspec/changes/remove-ai-tools-package/tasks.md deleted file mode 100644 index 707dd38..0000000 --- a/openspec/changes/remove-ai-tools-package/tasks.md +++ /dev/null @@ -1,12 +0,0 @@ -## 1. Implementation - -- [x] 1.1 Remove `nix-ai-tools` input from `flake.nix` -- [x] 1.2 Simplify `loadPackages` function to remove `nix-ai-tools` parameter -- [x] 1.3 Update `packages.nix` to single-parameter function signature -- [x] 1.4 Update `test/packages.nix` to single-parameter function signature -- [x] 1.5 Update `openspec/project.md` to remove nix-ai-tools references - -## 2. Validation - -- [x] 2.1 Run `nix flake check` to verify flake syntax (nix not available in environment - will be validated by CI) -- [ ] 2.2 Run Docker-based test suite to ensure shell integration still works diff --git a/openspec/project.md b/openspec/project.md deleted file mode 100644 index f7dd881..0000000 --- a/openspec/project.md +++ /dev/null @@ -1,107 +0,0 @@ -# Project Context - -## Purpose -Shelffiles is a portable environment configuration system that uses Nix to manage packages and configuration files. It provides a reproducible, XDG-compliant development environment that works consistently across different systems (Linux/macOS, x86_64/aarch64). - -**Key Goals:** -- Provide a portable, version-controlled development environment -- Support XDG Base Directory specification for configuration management -- Enable multi-user environments without conflicts (via user/group-specific paths) - -## Tech Stack -- **Nix Flakes** - Primary package management and reproducible builds -- **Shell scripting** - bash, zsh, fish -- **Bubblewrap** - Containerization fallback for isolated environments -- **https://github.com/sigoden/argcArgc** - CLI argument parsing framework -- **BATS** - Bash Automated Testing System for shell integration tests -- **Docker** - CI/CD testing environment and alternative build method -- **nix-portable** - Non-root Nix installation support - -## Project Conventions - -### Code Style -- **Shell scripts**: POSIX-compliant where possible, shellcheck-validated -- **Nix code**: Formatted with nixfmt (`nixfmt -c`) - -### Architecture Patterns -**Three-Layer Architecture:** - -1. **Nix Flakes Layer** - - `flake.nix`: Defines multi-architecture package environment - - `packages.nix`: User-customizable package list - -2. **XDG Environment Management** (`entrypoint/env.sh`) - - Sets XDG variables pointing to repository subdirectories - - Auto-creates cache/, share/, state/ directories - - To find XDG setting for tool, you can refer to [ARCH Linux wiki](https://wiki.archlinux.org/title/XDG_Base_Directory) - -3. **Shell Integration Layer** (`entrypoint/{bash,zsh,fish}`) - - Shell-specific launchers with appropriate variable settings - - Falls back to `launch_in_bwrap.sh` when Nix unavailable - -### Testing Strategy -**Test Framework:** BATS (Bash Automated Testing System) - -**Test Coverage:** -- Shell loading tests: `bashrc_load.bats`, `zshrc_load.bats`, `fishrc_load.bats` -- Each test verifies correct config loading via environment variables -- Test configs set `SHELFFILES_*_TEST="loaded"` flags - -**CI/CD Workflows:** -- **Docker Build**: Full integration test in clean environment -- **Lint**: Pre-commit hooks (shellcheck, hadolint, YAML, nixfmt) -- **Argc Verify**: Ensures setup.sh stays synced with argc generation -- **Claude Code**: AI assistant integration - -### Git Workflow -- **Main branch**: `main` (used for PRs and production) -- **Commit conventions**: Standard semantic commits encouraged -- **Special filters**: Git filter configuration in `example/config/git/` to exclude "shelffiles" lines from devcontainer.json commits -- **Protected paths**: packages.nix may be added to .gitignore for private configs -- **CI triggers**: PRs trigger lint, Docker build, argc verification - -## Domain Context -**Environment Management Concepts:** -- **XDG Base Directory Specification**: Standard for storing config/cache/data files -- **PATH_ID**: Unique identifier format `{SHELFFILES_path}_{USER_ID}_{GROUP_ID}` converted with `tr '/:' '__'` -- **Nix Store**: Immutable package storage, typically at /nix/store -- **Nix Flakes**: Modern Nix feature for reproducible package definitions -- **buildEnv**: Nix function that combines multiple packages into single environment -- **Bubblewrap**: Linux namespace sandboxing tool for containerization - -**Multi-Shell Support:** -- Each shell has unique config loading mechanism -- Bash: sources ~/.bashrc -- Zsh: uses $ZDOTDIR for config location -- Fish: loads from XDG_CONFIG_HOME/fish/config.fish - -## Important Constraints -**Technical Constraints:** -- `setup.sh` is argc-generated - do NOT manually edit argc-generated sections -- Regenerate setup.sh with: `argc --argc-build setup.sh > setup.sh` -- macOS does not support --no-root flag (nix-portable limitation) - -**Platform Support:** -- Linux: x86_64, aarch64 (full support) -- macOS: x86_64, aarch64 (full support, no --no-root) - -## External Dependencies -**Required Tools:** -- **Nix** : Package manager with flakes support - - Flakes enabled via `--extra-experimental-features nix-command flakes` - -**Optional/Fallback Tools:** -- **nix-portable**: Non-root Nix alternative (auto-installed by setup.sh --no-root) - - Source: https://github.com/DavHau/nix-portable -- **Bubblewrap**: Namespace containerization (for launch_in_bwrap.sh) -- **Docker**: CI testing and alternative build method - -**Build-time Dependencies:** -- **Argc**: CLI parsing framework for setup.sh - - Source: https://github.com/sigoden/argc -- **BATS**: Testing framework for shell scripts - - Included in packages.nix for test environments - -**Package Sources:** -- **nixpkgs**: Primary package repository (nixos-unstable channel) - - Search: https://search.nixos.org/packages