@leeovery/claude-technical-workflows 2.1.27 → 2.1.29

package/skills/technical-planning/references/output-formats/tick/about.md

@@ -0,0 +1,68 @@
+# Tick
+
+*Output format adapter for **[technical-planning](../../../SKILL.md)***
+
+---
+
+Use this format when you want structured task tracking with native dependency resolution, priority ordering, and token-efficient output designed for AI agents.
+
+## Benefits
+
+- Native dependency graph with cycle detection and blocking resolution
+- `tick ready` returns the next available task in one command
+- Token-efficient TOON output format (30-60% fewer tokens than JSON)
+- Git-friendly JSONL storage — append-only, human-readable
+- Parent/child hierarchy maps naturally to topic/phase/task structure
+- SQLite cache for fast queries over large task sets
+
+## Setup
+
+Install Tick:
+
+```bash
+# macOS
+brew install leeovery/tools/tick
+
+# Linux
+curl -fsSL https://raw.githubusercontent.com/leeovery/tick/main/scripts/install.sh | bash
+
+# Go
+go install github.com/leeovery/tick/cmd/tick@latest
+```
+
+Initialize in the project root:
+
+```bash
+tick init
+```
+
+Add to `.gitignore`:
+
+```
+.tick/.store
+.tick/lock
+```
+
+## Structure Mapping
+
+| Concept | Tick Entity |
+|---------|:---|
+| Topic | Top-level parent task |
+| Phase | Subtask of the topic task |
+| Task | Subtask of a phase task |
+| Dependency | Blocking relationship (`tick dep add`) |
+
+The 3-level hierarchy (topic → phase → task) uses Tick's parent/child system. Parent tasks are implicitly blocked by their children — a parent is not "ready" until all children are complete. Explicit dependencies (`tick dep add`) handle cross-phase and cross-topic blocking.
+
+## Output Location
+
+Tasks are stored in a `.tick/` directory at the project root:
+
+```
+.tick/
+├── tasks.jsonl     # Append-only source of truth (git-friendly)
+├── .store          # SQLite cache (auto-rebuilt, do not commit)
+└── lock            # File lock for concurrent access
+```
+
+All task data lives in `tasks.jsonl`. The hierarchy is encoded via parent references — no subdirectories needed.

package/skills/technical-planning/references/output-formats/tick/authoring.md

@@ -0,0 +1,106 @@
+# Tick: Authoring
+
+## Task Storage
+
+Tasks are created using the `tick create` command. Before creating individual tasks, establish the topic and phase parent tasks.
+
+**1. Create the topic task:**
+
+```bash
+tick create "{Topic Name}"
+```
+
+This returns the topic task ID (e.g., `tick-a1b2`).
+
+**2. Create phase tasks as children of the topic:**
+
+```bash
+tick create "Phase 1: {Phase Name}" --parent tick-a1b2
+tick create "Phase 2: {Phase Name}" --parent tick-a1b2
+```
+
+**3. Create tasks as children of their phase:**
+
+```bash
+tick create "{Task Title}" --parent tick-c3d4 \
+  --description "{Task description content.
+
+Acceptance criteria, edge cases, and implementation
+details go here. Supports multi-line text.}"
+```
+
+Complete example — creating a task under a phase:
+
+```bash
+tick create "Implement authentication middleware" \
+  --parent tick-c3d4 \
+  --description "Create Express middleware that validates JWT tokens on protected routes.
+
+Acceptance criteria:
+- Validates token signature and expiry
+- Extracts user ID from token payload
+- Returns 401 for missing or invalid tokens
+- Passes user context to downstream handlers"
+```
+
+## Task Properties
+
+### Status
+
+Tasks are created with `open` status by default.
+
+| Status | Meaning |
+|--------|---------|
+| `open` | Task has been authored but not started |
+| `in_progress` | Task is currently being worked on |
+| `done` | Task is complete |
+| `cancelled` | Task is no longer needed |
+
+### Phase Grouping
+
+Phases are represented as parent tasks. Each task belongs to a phase by being a child of that phase's task. Use `--parent <phase-id>` during creation.
+
+To list tasks within a phase:
+
+```bash
+tick list --parent <phase-id>
+```
+
+### Labels / Tags
+
+Tick does not have a native label or tag system. Categorisation is handled through the parent/child hierarchy.
+
+## Flagging
+
+When information is missing, prefix the task title with `[NEEDS INFO]` and include questions in the description:
+
+```bash
+tick create "[NEEDS INFO] Rate limiting strategy" \
+  --parent tick-c3d4 \
+  --description "Needs clarification:
+- What is the rate limit threshold?
+- Per-user or per-IP?
+- What response code on limit exceeded?"
+```
+
+## Cleanup (Restart)
+
+Cancel the topic task and all its descendants. First, list the tasks to collect their IDs:
+
+```bash
+tick list --parent <topic-id>
+```
+
+Then cancel each task (leaf tasks first, then phases, then the topic):
+
+```bash
+tick cancel <task-id>
+```
+
+Cancelled tasks remain in the JSONL history but are excluded from `tick ready` and active listings.
+
+**Full reset** (removes all tasks across all topics):
+
+```bash
+rm -rf .tick && tick init
+```

package/skills/technical-planning/references/output-formats/tick/graph.md

@@ -0,0 +1,62 @@
+# Tick: Task Graph
+
+Tick has native support for priority and blocking dependencies with cycle detection. This file is used by the graphing agent after all tasks have been authored.
+
+## Priority
+
+| Level | Name | Value |
+|-------|------|-------|
+| 0 | Critical | Highest priority |
+| 1 | High | |
+| 2 | Medium | Default |
+| 3 | Low | |
+| 4 | Backlog | Lowest priority |
+
+Lower number = higher priority. Tasks are created with priority `2` (medium) by default.
+
+### Setting Priority
+
+```bash
+tick update <task-id> --priority 1
+```
+
+### Removing Priority
+
+Reset to the default medium priority:
+
+```bash
+tick update <task-id> --priority 2
+```
+
+Tick does not support unsetting priority — every task has a priority level. Use `2` (medium) as the neutral default.
+
+## Dependencies
+
+Tick validates all dependency changes: prevents cycles, self-references, and children blocked by their own parent.
+
+### Adding a Dependency
+
+Declare that a task is blocked by another task:
+
+```bash
+tick dep add <task-id> <blocked-by-id>
+```
+
+Example — task `tick-e5f6` depends on `tick-a1b2`:
+
+```bash
+tick dep add tick-e5f6 tick-a1b2
+```
+
+To add multiple dependencies to a single task, run the command for each:
+
+```bash
+tick dep add tick-e5f6 tick-a1b2
+tick dep add tick-e5f6 tick-c3d4
+```
+
+### Removing a Dependency
+
+```bash
+tick dep rm <task-id> <blocked-by-id>
+```

package/skills/technical-planning/references/output-formats/tick/reading.md

@@ -0,0 +1,61 @@
+# Tick: Reading
+
+## Listing Tasks
+
+To retrieve all tasks for a topic:
+
+```bash
+tick list --parent <topic-id>
+```
+
+This returns all descendants (phases and tasks) with summary-level data: id, title, status, priority, and parent. Results are sorted by priority (ascending), then creation date.
+
+To list tasks within a specific phase:
+
+```bash
+tick list --parent <phase-id>
+```
+
+Additional filtering:
+
+```bash
+tick list --parent <topic-id> --status open       # only open tasks
+tick list --parent <topic-id> --ready              # ready tasks only
+tick list --parent <topic-id> --blocked            # blocked tasks only
+tick list --parent <topic-id> --priority 0         # critical tasks only
+```
+
+## Extracting a Task
+
+To read full task detail including description, blockers, and children:
+
+```bash
+tick show <task-id>
+```
+
+Returns: id, title, status, priority, created/updated timestamps, parent, blocked_by list, children list, and full description.
+
+## Next Available Task
+
+To find the next task to implement:
+
+```bash
+tick ready --parent <phase-id>
+```
+
+This returns tasks that are:
+
+1. Status is `open` (not started, not done, not cancelled)
+2. No unresolved blockers (all `blocked_by` tasks are `done`)
+3. No open children (leaf tasks, or parent tasks whose children are all complete)
+4. Within the specified phase (scoped by `--parent`)
+
+Results are sorted by priority (lower number = higher priority), then creation date. The first result is the next task.
+
+To find the next task across all phases of a topic:
+
+```bash
+tick ready --parent <topic-id>
+```
+
+If `tick ready` returns no results, either all tasks are complete or remaining tasks are blocked.

package/skills/technical-planning/references/output-formats/tick/updating.md

@@ -0,0 +1,25 @@
+# Tick: Updating
+
+## Status Transitions
+
+Tick uses dedicated commands for each status transition:
+
+| Transition | Command |
+|------------|---------|
+| Start | `tick start <task-id>` (open → in_progress) |
+| Complete | `tick done <task-id>` (in_progress → done) |
+| Cancelled | `tick cancel <task-id>` (any → cancelled) |
+| Reopen | `tick reopen <task-id>` (done/cancelled → open) |
+| Skipped | `tick cancel <task-id>` (no separate skipped status — use cancel) |
+
+`done` and `cancel` set a closed timestamp. `reopen` clears it.
+
+## Updating Task Content
+
+To update a task's properties:
+
+- **Title**: `tick update <task-id> --title "New title"`
+- **Description**: `tick update <task-id> --description "New description"`
+- **Priority**: `tick update <task-id> --priority 1`
+- **Parent**: `tick update <task-id> --parent <new-parent-id>` (pass empty string to clear)
+- **Dependencies**: See [graph.md](graph.md)

package/skills/technical-planning/references/output-formats.md

@@ -33,3 +33,14 @@ Tasks managed as Linear issues within a Linear project. A thin Plan Index File p
 - **Pros**: Visual tracking, team collaboration, real-time updates, integrates with existing Linear workflows
 - **Cons**: Requires Linear account and MCP server, external dependency, not fully local
 - **Best for**: Teams already using Linear, collaborative projects needing shared visibility
+
+### Tick
+format: `tick`
+
+adapter: [tick/](output-formats/tick/)
+
+CLI task management with native dependencies, priority, and token-efficient output designed for AI agents. Tasks stored in git-friendly JSONL with a SQLite cache.
+
+- **Pros**: Native dependency graph with cycle detection, `tick ready` for next-task resolution, token-efficient TOON output, git-friendly, works offline
+- **Cons**: Requires Tick CLI installation, no visual board or web UI
+- **Best for**: AI-driven workflows needing structured task tracking with dependency resolution

package/skills/technical-planning/references/{steps/plan-construction.md → plan-construction.md}

@@ -1,6 +1,6 @@
 # Plan Construction
 
-*Reference for **[technical-planning](../../SKILL.md)***
+*Reference for **[technical-planning](../SKILL.md)***
 
 ---
 
@@ -51,9 +51,13 @@ After the phase structure is approved, continue to **Process Phases** below.
 
 Work through each phase in order.
 
-Orient the user:
+> *Output the next fenced block as a code block:*
 
-"I'll now work through each phase — presenting existing work for review and designing or authoring anything still pending. You'll approve at every stage."
+```
+I'll now work through each phase — presenting existing work for review
+and designing or authoring anything still pending. You'll approve at
+every stage.
+```
 
 ### For each phase, check its state:
 
@@ -67,10 +71,14 @@ After Step A returns with an approved task table, continue to **Author Tasks for
 
 #### If the phase has a task table
 
-Present the task list to the user as rendered markdown (not in a code block).
+> *Output the next fenced block as markdown (not a code block):*
 
+```
 **Phase {N}: {Phase Name}** — {M} tasks.
 
+{task list from the phase's task table}
+```
+
 > *Output the next fenced block as markdown (not a code block):*
 
 ```
@@ -84,9 +92,13 @@ Present the task list to the user as rendered markdown (not in a code block).
 
 **STOP.** Wait for the user's response.
 
-**If the user wants changes:** → Go to **Step A** with this phase for revision.
+#### If the user wants changes
+
+→ Go to **Step A** with this phase for revision.
 
-**If confirmed:** Continue to **Author Tasks for the Phase** below.
+#### If confirmed
+
+→ Continue to **Author Tasks for the Phase** below.
 
 ---
 
@@ -107,9 +119,13 @@ Never parallelize the first `pending` task in a phase. Never parallelize across
 
 #### If the task status is `authored`
 
-Already written. Present a brief summary:
+Already written.
+
+> *Output the next fenced block as a code block:*
 
-"Task {M} of {total}: {Task Name} — already authored."
+```
+Task {M} of {total}: {Task Name} — already authored.
+```
 
 Continue to the next task.
 
@@ -123,7 +139,11 @@ After Step B returns, the task is authored. Continue to the next task.
 
 Advance the `planning:` block in frontmatter to the next phase. Commit: `planning({topic}): complete Phase {N} tasks`
 
+> *Output the next fenced block as a code block:*
+
+```
 Phase {N}: {Phase Name} — complete ({M} tasks authored).
+```
 
 Continue to the next phase.
 
@@ -133,7 +153,11 @@ Continue to the next phase.
 
 When all phases have all tasks authored:
 
-"All phases are complete. The plan has **{N} phases** with **{M} tasks** total."
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+All phases are complete. The plan has **{N} phases** with **{M} tasks** total.
+```
 
 ---
 

package/skills/technical-planning/references/plan-review.md

@@ -0,0 +1,122 @@
+# Plan Review
+
+*Reference for **[technical-planning](../SKILL.md)***
+
+---
+
+Two-part review dispatched to sub-agents. Traceability runs first — its approved fixes are applied before the integrity review begins, so integrity evaluates the corrected plan.
+
+---
+
+## A. Cycle Management
+
+Check the `review_cycle` field in the Plan Index File frontmatter.
+
+#### If `review_cycle` is missing or not set
+
+Add `review_cycle: 1` to the Plan Index File frontmatter.
+
+#### If `review_cycle` is already set
+
+Increment `review_cycle` by 1.
+
+Record the current cycle number — passed to both review agents for tracking file naming (`c{N}`).
+
+→ Proceed to **B. Traceability Review**.
+
+---
+
+## B. Traceability Review
+
+1. Load **[invoke-review-traceability.md](invoke-review-traceability.md)** and follow its instructions to dispatch the agent.
+2. **STOP.** Do not proceed until the agent has returned its result.
+3. On receipt of result, load **[process-review-findings.md](process-review-findings.md)** and follow its instructions to process the findings with the user.
+
+→ Proceed to **C. Plan Integrity Review**.
+
+---
+
+## C. Plan Integrity Review
+
+1. Load **[invoke-review-integrity.md](invoke-review-integrity.md)** and follow its instructions to dispatch the agent.
+2. **STOP.** Do not proceed until the agent has returned its result.
+3. On receipt of result, load **[process-review-findings.md](process-review-findings.md)** and follow its instructions to process the findings with the user.
+
+→ Proceed to **D. Re-Loop Prompt**.
+
+---
+
+## D. Re-Loop Prompt
+
+#### If no findings were surfaced in this cycle
+
+→ Proceed directly to **E. Completion**.
+
+#### If findings were surfaced
+
+Check `finding_gate_mode` and `review_cycle` in the Plan Index File frontmatter.
+
+#### If `finding_gate_mode: auto` and `review_cycle < 5`
+
+Announce (one line, no stop):
+
+> *Output the next fenced block as a code block:*
+
+```
+Review cycle {N} complete — findings applied. Running follow-up cycle.
+```
+
+→ Return to **A. Cycle Management**.
+
+#### If `finding_gate_mode: auto` and `review_cycle >= 5`
+
+Review has auto-cycled 5 times without converging. Escalating for human review.
+
+→ Present the gated re-loop prompt below.
+
+#### If `finding_gate_mode: gated`
+
+> *Output the next fenced block as a code block:*
+
+```
+Fixes applied this cycle may have shifted dependencies, introduced gaps,
+or affected other tasks. A follow-up round reviews the corrected plan
+with fresh context — 2-3 cycles typically surface anything cascading.
+```
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+- **`r`/`reanalyse`** — Run another round of review (traceability + integrity)
+- **`p`/`proceed`** — Proceed to conclusion
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If reanalyse
+
+→ Return to **A. Cycle Management** to begin a fresh cycle.
+
+#### If proceed
+
+→ Continue to **E. Completion**.
+
+---
+
+## E. Completion
+
+1. **Verify tracking files are marked complete** — All traceability and integrity tracking files across all cycles must have `status: complete`.
+
+> **CHECKPOINT**: Do not confirm completion if any tracking files still show `status: in-progress`. They indicate incomplete review work.
+
+2. **Commit** all review tracking files: `planning({topic}): complete plan review (cycle {N})`
+
+> *Output the next fenced block as a code block:*
+
+```
+Plan review complete — {N} cycle(s), all tracking files finalised.
+```
+
+→ Return to **[technical-planning SKILL.md](../SKILL.md)** for **Step 8**.