osx-maintain-ai-docs

Update project documentation after implementing an OpenSpec change. **Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes. --- ## Core Principles | Principle | Application | |-----------|-------------| | **Ruthless conciseness** | Only document what AI can't infer from code | | **Progressive disclosure** | Reference details, don't embed them | | **Token efficiency** | Tables over verbose lists, front-load essentials | | **Specificity** | Concrete commands, not vague instructions | **Target lengths**: - Ideal: <300 lines (~1200 tokens) - Warning: >300 lines (review needed) - Maximum: >500 lines (must split) --- ## Steps 1. **Select the change** If a name is provided, use it. Otherwise: - Infer from conversation context if the user mentioned a change - Auto-select if only one active change exists - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select Always announce: "Using change: <name>" and how to override. 2. **Read change artifacts** Read files from `openspec/changes/<name>/`: | File | Extract | |------|---------| | `proposal.md` | Intent, scope, new features/capabilities | | `specs/` | New requirements, modified behaviors | | `design.md` | Architectural decisions, new patterns, file changes | | `tasks.md` | Checked items = what was a...