aether-colony 3.1.17 → 5.1.0

package/runtime/docs/planning-discipline.md

@@ -1,159 +0,0 @@
-# Planning Discipline
-
-## Purpose
-
-Write comprehensive implementation plans with bite-sized tasks, assuming workers have zero context. Each task should be one action (2-5 minutes of work).
-
-## Core Principles
-
-- **DRY** - Don't Repeat Yourself
-- **YAGNI** - You Aren't Gonna Need It
-- **TDD** - Test-Driven Development (test first, always)
-- **Frequent Commits** - One commit per feature/fix
-
-## Bite-Sized Task Granularity
-
-**Each step is ONE action:**
-
-```
-"Write the failing test" - step
-"Run it to make sure it fails" - step
-"Implement the minimal code to make the test pass" - step
-"Run the tests and make sure they pass" - step
-"Commit" - step
-```
-
-**NOT acceptable:**
-- "Implement authentication with tests" (too big)
-- "Add validation" (too vague)
-- "Set up the project" (needs breakdown)
-
-## Task Structure
-
-Each task should include:
-
-### 1. Files Section
-
-```markdown
-**Files:**
-- Create: `exact/path/to/file.py`
-- Modify: `exact/path/to/existing.py:123-145`
-- Test: `tests/exact/path/to/test.py`
-```
-
-Always use exact paths. No "somewhere in src/" ambiguity.
-
-### 2. Steps with TDD Flow
-
-```markdown
-**Step 1: Write the failing test**
-
-\`\`\`python
-def test_specific_behavior():
-    result = function(input)
-    assert result == expected
-\`\`\`
-
-**Step 2: Run test to verify it fails**
-
-Run: `pytest tests/path/test.py::test_name -v`
-Expected: FAIL with "function not defined"
-
-**Step 3: Write minimal implementation**
-
-\`\`\`python
-def function(input):
-    return expected
-\`\`\`
-
-**Step 4: Run test to verify it passes**
-
-Run: `pytest tests/path/test.py::test_name -v`
-Expected: PASS
-
-**Step 5: Commit**
-
-\`\`\`bash
-git add tests/path/test.py src/path/file.py
-git commit -m "feat: add specific feature"
-\`\`\`
-```
-
-### 3. Expected Output
-
-For every command, specify expected output:
-
-```markdown
-Run: `npm test`
-Expected: 47 passing, 0 failing
-```
-
-Not just "run tests" - specify what success looks like.
-
-## Phase Structure
-
-```markdown
-### Phase N: [Component Name]
-
-**Goal:** [One sentence describing what this phase achieves]
-
-**Dependencies:** [What must exist before this phase]
-
-**Tasks:**
-
-#### Task N.1: [Specific action]
-
-**Files:**
-- Create: `src/components/Button.tsx`
-- Test: `tests/components/Button.test.tsx`
-
-**Steps:**
-(TDD steps as above)
-
-**Success Criteria:**
-- Tests pass for Button component
-- Component renders without errors
-```
-
-## Quality Checks
-
-Before a plan is complete, verify:
-
-1. **Exact paths** - Every file reference is complete path
-2. **Complete code** - No "add appropriate code" placeholders
-3. **Expected outputs** - Every command has expected result
-4. **TDD flow** - Test before implementation for each feature
-5. **No assumptions** - Worker could execute with zero context
-6. **Commit points** - Clear where to commit
-
-## Integration with Colony
-
-The Route-Setter Ant follows this discipline when generating plans.
-
-Each task in `plan.phases[N].tasks` should be:
-- Executable in 2-5 minutes
-- Self-contained with file paths
-- Verifiable with specific success criteria
-
-## Red Flags
-
-**Never in a plan:**
-- "Add tests" (which tests? for what?)
-- "Implement feature" (what specifically?)
-- "Update file" (which file? what changes?)
-- "Handle edge cases" (which cases?)
-
-**Always in a plan:**
-- Exact file paths
-- Complete code snippets
-- Exact commands to run
-- Expected outputs/results
-- One action per step
-
-## Why This Matters
-
-- Workers can execute without asking questions
-- Progress is measurable (step by step)
-- Debugging is easier (clear steps to trace)
-- Commits are atomic and meaningful
-- Quality is built in (TDD from start)

package/runtime/docs/progressive-disclosure.md

@@ -1,184 +0,0 @@
-# Progressive Disclosure Output Format Standard
-
-This specification defines the standard output format for all Aether CLI commands, enabling compact summaries with optional detailed expansion.
-
-## Core Principles
-
-1. **Default to compact**: Single-line summaries by default
-2. **Show counts**: Use bracketed counts to indicate expandable detail
-3. **Consistent triggers**: `--verbose` or `-v` expands all sections
-
-## Format Specification
-
-### Summary Line Format
-
-```
-<command>: <primary-metric> | <secondary-metrics...> [<count> <type>]
-```
-
-**Examples:**
-```
-status: clean | 3 staged, 1 modified [4 changes]
-build: success | 2.3s [12 warnings]
-plan: ready | 5 tasks [3 blocked]
-```
-
-### Count Format
-
-Counts indicate expandable sections. Format:
-
-```
-[N <plural-noun>]
-```
-
-**Rules:**
-- Always use brackets `[]`
-- Number first, then descriptive noun
-- Use plural form even for count of 1 (consistency)
-- Noun should describe what expands, not the data type
-
-**Examples:**
-```
-[3 TODOs]        # Expands to show 3 TODO items
-[1 errors]       # Expands to show error details
-[5 files]        # Expands to show file list
-[12 warnings]    # Expands to show warning messages
-```
-
-### Expansion Trigger
-
-| Flag | Effect |
-|------|--------|
-| (none) | Compact single-line output |
-| `-v` / `--verbose` | Expand all bracketed counts |
-| `--verbose=<section>` | Expand specific section only |
-
-### Multi-Section Output
-
-When multiple expandable sections exist, list them inline:
-
-```
-status: clean | [3 TODOs] [2 FIXMEs] [1 errors]
-```
-
-With `--verbose`, each section expands under a header:
-
-```
-status: clean | [3 TODOs] [2 FIXMEs] [1 errors]
-
-TODOs:
-  - src/main.rs:42: implement caching
-  - src/lib.rs:15: add error handling
-  - tests/mod.rs:8: add integration test
-
-FIXMEs:
-  - src/parser.rs:23: handle edge case
-  - src/parser.rs:67: optimize loop
-
-Errors:
-  - build failed in module 'auth'
-```
-
-## Command-Specific Formats
-
-### status
-
-```
-# Compact
-status: clean | 3 staged, 1 modified [4 changes]
-
-# Verbose
-status: clean | 3 staged, 1 modified [4 changes]
-
-Changes:
-  M  src/main.rs
-  A  src/new_file.rs
-  A  src/another.rs
-  M  README.md
-```
-
-### build
-
-```
-# Compact
-build: success | 2.3s [12 warnings]
-
-# Verbose
-build: success | 2.3s [12 warnings]
-
-Warnings:
-  src/lib.rs:45: unused variable 'x'
-  src/lib.rs:67: deprecated function call
-  ...
-```
-
-### plan
-
-```
-# Compact
-plan: ready | 5 tasks, 2 blocked [3 pending]
-
-# Verbose
-plan: ready | 5 tasks, 2 blocked [3 pending]
-
-Pending:
-  - [ ] Task 1.1: Setup infrastructure
-  - [ ] Task 1.2: Configure dependencies
-  - [ ] Task 2.1: Implement core logic
-```
-
-### todos
-
-```
-# Compact
-todos: [3 TODOs] [2 FIXMEs] [1 HACK]
-
-# Verbose
-todos: [3 TODOs] [2 FIXMEs] [1 HACK]
-
-TODOs:
-  src/main.rs:42: implement caching
-  src/lib.rs:15: add error handling
-  tests/mod.rs:8: add integration test
-
-FIXMEs:
-  src/parser.rs:23: handle edge case
-  src/parser.rs:67: optimize loop
-
-HACK:
-  src/temp.rs:5: temporary workaround for API bug
-```
-
-## Implementation Notes
-
-### For Command Authors
-
-1. Always output the summary line first
-2. Detect `--verbose` flag before formatting
-3. Use consistent indentation (2 spaces) for expanded content
-4. Include file:line references where applicable
-5. Truncate long lists with `...` and count (e.g., `... and 15 more`)
-
-### Integration
-
-Reference this spec in command implementations:
-
-```rust
-// See .aether/docs/progressive-disclosure.md for output format
-```
-
-```python
-# Output format: .aether/docs/progressive-disclosure.md
-```
-
-## Color Guidelines (Terminal)
-
-When outputting to a TTY:
-- Counts in brackets: dim/gray
-- Success states: green
-- Warning counts: yellow
-- Error counts: red
-- File paths: cyan
-- Line numbers: dim
-
-When piped or redirected: no color codes.