safeword 0.2.3 → 0.2.4

package/.safeword/tickets/008-upgrade-questioning.md

@@ -0,0 +1,58 @@
+---
+id: 008
+status: pending
+created: 2025-11-27
+github: https://github.com/TheMostlyGreat/safeword/issues/4
+---
+
+# Upgrade Questioning - Requirements Gathering
+
+**Goal:** Add proactive questioning for requirements gathering BEFORE implementation, not just during quality review.
+
+**Why:** Current questioning only happens in quality review (after changes). Need questioning skill for upfront requirements clarification.
+
+## Problem
+
+Agent often starts implementing without clarifying:
+
+- Ambiguous requirements
+- Missing acceptance criteria
+- Undefined edge cases
+- Technology preferences
+
+**Result:** Rework, wrong direction, wasted cycles.
+
+## Scope
+
+**New capability:** Requirements questioning skill
+
+**Key scenarios:**
+
+1. **Feature request** - Clarify scope, acceptance criteria, constraints
+2. **Bug report** - Clarify repro steps, expected behavior, severity
+3. **Refactoring** - Clarify goals, constraints, risk tolerance
+4. **Design decision** - Clarify priorities, trade-offs, timeline
+
+**Question protocol:**
+
+- Ask upfront (before implementation)
+- Limit to 2-3 key questions
+- Provide defaults/assumptions if user doesn't answer
+- Document answers in ticket/planning docs
+
+## Deliverables
+
+- `framework/skills/requirements-questioning/SKILL.md`
+- Integration with ticket system (questions → ticket answers)
+- Update SAFEWORD.md workflow with questioning step
+
+## Acceptance Criteria
+
+- [ ] Skill file with clear triggers and protocol
+- [ ] Question templates for each scenario
+- [ ] Integration with planning docs workflow
+- [ ] Maximum question limits to avoid fatigue
+
+## Work Log
+
+- 2025-11-27 Created ticket

package/.safeword/tickets/009-naming-conventions.md

@@ -0,0 +1,41 @@
+---
+id: 009
+status: pending
+created: 2025-11-27
+github: https://github.com/TheMostlyGreat/safeword/issues/5
+---
+
+# Fix File Naming Conventions
+
+**Goal:** Standardize naming for tickets vs derived planning docs vs standalone docs.
+
+**Why:** Current naming is inconsistent. Hard to see which planning docs belong to which tickets.
+
+## Naming Rules
+
+| File Type           | Pattern                 | Example                                                |
+| ------------------- | ----------------------- | ------------------------------------------------------ |
+| **Tickets**         | `{NNN}-{slug}.md`       | `001-fix-login-bug.md`                                 |
+| **Derived docs**    | `{NNN}.{XX}-{slug}.md`  | `001.01-user-stories.md`, `001.02-test-definitions.md` |
+| **Standalone docs** | `{slug}.md` (no number) | `architecture-enforcement-system.md`                   |
+
+## Rules
+
+1. **Tickets** stay numbered: `001-`, `002-`, etc.
+2. **Planning docs derived from a ticket** append `.XX` sub-number
+   - First planning doc: `001.01-user-stories.md`
+   - Second: `001.02-design-doc.md`
+   - Allows sorting while showing relationship
+3. **Standalone planning docs** (bigger scope than any ticket) get no number
+   - Cross-cutting concerns, research, multi-ticket planning
+   - Example: `architecture-enforcement-system.md`
+
+## Acceptance Criteria
+
+- [ ] SAFEWORD.md updated with naming convention
+- [ ] Existing files renamed to match
+- [ ] Ticket template includes derived doc naming guidance
+
+## Work Log
+
+- 2025-11-27 Created ticket

package/.safeword/tickets/010-safeword-md-cleanup.md

@@ -0,0 +1,34 @@
+---
+id: 010
+status: pending
+priority: high
+created: 2025-11-27
+github: https://github.com/TheMostlyGreat/safeword/issues/6
+---
+
+# Clean Up SAFEWORD.md
+
+**Goal:** Streamline and modernize SAFEWORD.md for clarity and maintainability.
+
+**Why:** Core file that all AI agents read. Bloated/unclear instructions = confused agents = wasted cycles.
+
+## Scope
+
+**Review and clean:**
+
+- Remove duplication
+- Tighten language (brevity, clarity)
+- Update outdated sections
+- Improve structure/hierarchy
+- Ensure consistency with guides
+
+## Acceptance Criteria
+
+- [ ] Reduced line count without losing value
+- [ ] Clear section hierarchy
+- [ ] No duplicated content with guides
+- [ ] All cross-references valid
+
+## Work Log
+
+- 2025-11-27 Created ticket (high priority)

package/.safeword/tickets/011-cursor-setup.md

@@ -0,0 +1,86 @@
+---
+id: 011
+status: pending
+created: 2025-11-27
+github: https://github.com/TheMostlyGreat/safeword/issues/7
+---
+
+# Add Cursor Setup Support
+
+**Goal:** Create `setup-cursor.sh` script that sets up Cursor IDE with SAFEWORD patterns, parallel to `setup-claude.sh`.
+
+**Why:** Cursor is a popular AI-powered IDE. Teams using Cursor need the same SAFEWORD enforcement (TDD workflow, quality standards, guides) that Claude Code users get.
+
+## Scope
+
+**In scope:**
+
+- `setup-cursor.sh` - Sets up Cursor-specific configurations
+- `.cursorrules` file with SAFEWORD trigger
+- `.cursor/mcp.json` for MCP server configurations (Context7, etc.)
+- `CURSOR.md` project context file (optional, when CLAUDE.md doesn't exist)
+- Integration with existing `setup-safeword.sh` (detect and offer Cursor setup)
+
+**Out of scope:**
+
+- Cursor-specific hooks (Cursor doesn't support hooks like Claude Code)
+- Linting setup (already handled by `setup-linting.sh`, works for any editor)
+- CLI integration (`safeword init --cursor` - that's for the CLI ticket)
+
+## Technical Notes
+
+Cursor uses these files:
+
+- `.cursorrules` - Project-level rules (like `.claude/settings.json` but simpler)
+- `.cursor/mcp.json` - MCP server configurations
+- `.cursor/rules/` - Directory for multiple rule files (alternative to single `.cursorrules`)
+
+Key differences from Claude setup:
+
+- No hooks system (Cursor doesn't have pre/post command hooks)
+- Rules are simpler - just instructions, no JSON config
+- MCP config format differs from Claude's
+
+## Acceptance Criteria
+
+- [ ] `bash setup-cursor.sh` creates `.cursorrules` with SAFEWORD trigger
+- [ ] `.cursorrules` references `@./.safeword/SAFEWORD.md`
+- [ ] Script creates `.cursor/mcp.json` with Context7 config
+- [ ] Script is idempotent (safe to run multiple times)
+- [ ] Script detects existing `.cursorrules` and appends (doesn't overwrite)
+- [ ] `setup-safeword.sh` mentions Cursor setup as next step
+- [ ] README updated with Cursor setup instructions
+
+## Implementation Notes
+
+`.cursorrules` content should include:
+
+```markdown
+# Project Rules
+
+**⚠️ ALWAYS READ FIRST: @./.safeword/SAFEWORD.md**
+
+The SAFEWORD.md file contains core development patterns, workflows, and conventions.
+Read it BEFORE working on any task in this project.
+
+---
+
+[Project-specific Cursor rules go here]
+```
+
+`.cursor/mcp.json` should include Context7 (and optionally Arcade):
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"]
+    }
+  }
+}
+```
+
+## Work Log
+
+- 2025-11-27 Created ticket

package/.safeword/tickets/README.md

@@ -0,0 +1,73 @@
+# Tickets
+
+Higher-level feature/epic tracking. Each ticket references planning docs.
+
+## Structure
+
+- `./` - Active tickets (in progress or todo)
+- `completed/` - Verified completed tickets (user confirmed)
+- `archived/` - Blocked or cancelled tickets
+
+## Naming Convention
+
+**Tickets:** `{id}-{feature-slug}.md`
+- Example: `001-user-authentication.md`, `002-payment-flow.md`
+
+**Planning docs share same prefix:**
+- User stories: `./.safeword/planning/user-stories/001-user-authentication.md`
+- Test definitions: `./.safeword/planning/test-definitions/001-user-authentication.md`
+- Design doc: `./.safeword/planning/design/001-user-authentication.md`
+
+This makes it easy to find all related docs by prefix.
+
+## Format
+
+```markdown
+---
+id: 001
+status: todo|in_progress|done|blocked
+created: 2025-01-19T14:30:00Z
+priority: low|medium|high
+planning_refs:
+  - ./.safeword/planning/user-stories/001-user-authentication.md
+  - ./.safeword/planning/test-definitions/001-user-authentication.md
+  - ./.safeword/planning/design/001-user-authentication.md (if complex)
+---
+
+# User Authentication System
+
+## Description
+{High-level feature description}
+
+## Scope
+{What's included in this ticket}
+
+## Acceptance Criteria
+- [ ] All user stories completed
+- [ ] All tests passing
+- [ ] Documentation updated
+
+## Work Log
+{Progress notes, decisions, blockers}
+```
+
+## Completion Process
+
+**CRITICAL:** Never mark ticket as done or archive without user confirmation.
+
+1. Update status to `done` when work complete
+2. **Ask user to confirm** all acceptance criteria met
+3. User verifies:
+   - All tests passing
+   - Feature works as expected
+   - No regressions introduced
+4. After confirmation: Move to `completed/`
+5. Blocked/cancelled tickets: Move to `archived/`
+
+## Relationship
+
+- **Ticket** = Higher-level feature/epic
+- **Planning docs** = Detailed specs (user stories, test definitions, design)
+- **TodoWrite** = Task-level tracking in current session
+
+See `@./.safeword/SAFEWORD.md` → Ticket System for details.

package/.safeword/version

@@ -0,0 +1 @@
+0.1.0

package/AGENTS.md

@@ -0,0 +1,59 @@
+**⚠️ ALWAYS READ FIRST: @./.safeword/SAFEWORD.md**
+
+The SAFEWORD.md file contains core development patterns, workflows, and conventions.
+Read it BEFORE working on any task in this project.
+
+---
+
+# SAFEWORD - AI Agent Configuration CLI
+
+A CLI tool that sets up AI coding agent configurations (guides, hooks, templates) for any project.
+
+## Project Purpose
+
+**What:** `npx safeword setup` installs a `.safeword/` directory with guides, templates, and hooks into user projects.
+
+**This repo is safeword's source code AND uses safeword itself (dogfooding).**
+
+## Directory Roles
+
+| Directory | Role |
+|-----------|------|
+| `framework/` | **Source templates** - What the CLI copies to user projects |
+| `packages/cli/` | **CLI source** - The `npx safeword` tool itself |
+| `.safeword/` | **Dogfooding** - This project's own installed safeword config (tracked, generated by CLI) |
+| `.claude/` | **Claude Code config** - Hooks, commands, skills for this project |
+
+## Tech Stack
+
+| Component | Technology |
+|-----------|------------|
+| CLI | TypeScript, Commander.js, Node 18+ |
+| Build | tsup (ESM-only output) |
+| Tests | Vitest, promptfoo (LLM evals) |
+| Linting | ESLint 9 + Prettier |
+
+## Development Workflow
+
+### Editing Source Templates
+
+1. Edit in `framework/` (source of truth)
+2. Run `npx safeword upgrade` to sync to `.safeword/`
+3. Run evals: `npm run eval`
+
+### Running LLM Evals
+
+```bash
+npm run eval           # Run all tests
+npm run eval:view      # Open web UI for results
+```
+
+**Requires:** `ANTHROPIC_API_KEY` environment variable
+
+## Common Gotchas
+
+1. **framework/ vs .safeword/**: Edit `framework/` first, then run `npx safeword upgrade` to sync.
+
+2. **Eval failures**: Usually means the guide needs clearer instructions, not that the test is wrong.
+
+3. **Planning docs location**: All planning goes in `.safeword/planning/` per the SAFEWORD.md conventions.

package/CLAUDE.md

@@ -0,0 +1,12 @@
+# Project Claude Context
+
+**⚠️ ALWAYS READ FIRST: @./.safeword/SAFEWORD.md**
+
+The SAFEWORD.md file contains core development patterns, workflows, and conventions.
+Read it BEFORE working on any task in this project.
+
+---
+
+## Project-Specific Guidance
+
+- Add Claude-specific context, commands, or workflow notes here