dctracker 1.0.0__py3-none-any.whl

dct/skills/handoff/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: handoff
+description: |
+  End-of-session workflow — flag items as next-sprint and leave a handoff prompt
+  for the next session.
+  Use when: "handoff", "zakończ sesję", "do następnej sesji", "end session",
+  "hand off", "zrób handoff", "wrap up".
+---
+
+# /handoff — Session Handoff
+
+Finalize a coding session by (a) marking which items belong to the next sprint
+and (b) optionally writing a prompt for the next session to pick up.
+
+## Workflow
+
+### Step 1: Detect project
+
+Call `mcp__dct__list_projects` and match against CWD (longest path prefix).
+If CWD is not a registered project, ask user via `AskUserQuestion`:
+  - question: "Which project is this handoff for?"
+  - options: list of registered project slugs + "Cancel"
+
+### Step 2: Offer scope tag
+
+Ask via `AskUserQuestion`:
+  - question: "Optional scope tag for this handoff (helps disambiguate when multiple sessions run in parallel)?"
+  - options: "No scope", "sprint-v<next>", "refactor-<area>", "Other (type in)"
+  - If user picks "Other", follow up with free-text AskUserQuestion.
+
+Remember the chosen `scope` (may be empty).
+
+### Step 3: Show current sprint + propose items
+
+Call `mcp__dct__review_sprint(project, since="last_release")` to get:
+  - current `in_sprint` list (what's already flagged)
+  - `recent_activity` — items touched since last release
+  - `stale_in_progress` — items blocked or forgotten
+
+**Empty project fallback** — if all sections are empty (no items at all in
+the project, or everything is resolved), offer via `AskUserQuestion`:
+- question: "Nothing to propose — project has no open or recent items. What now?"
+- options: `"Skip sprint proposal — just write handoff prompt"` / `"Cancel /handoff"` / `"Run /track-list to browse state first"`.
+
+Present a draft sprint proposal based on:
+  - All P1 open items (always)
+  - Top 3-5 P2 open items with existing checkpoints
+  - Any items currently in `recent_activity` that are still open
+
+Ask via `AskUserQuestion`:
+  - question: "Which items go into the next sprint? (IDs, comma-separated, or 'keep current', or 'empty sprint')"
+  - options: the proposed list formatted as "22, 21, 6 (proposed)" | "Keep current sprint" | "Empty sprint" | "Custom list (type in)"
+  - On "Custom list" — follow up with free-text ids.
+
+### Step 4: Set sprint
+
+Parse chosen ids. Call `mcp__dct__set_sprint(project, item_ids="22,21,6")`
+(or with empty string for empty sprint, or skip this step if "Keep current").
+
+### Step 5: Optionally write handoff prompt
+
+Ask via `AskUserQuestion`:
+  - question: "Write a prompt for the next session?"
+  - options:
+    - "Yes — I'll dictate" (user types freely)
+    - "Yes — auto-draft from sprint context" (assistant drafts, user confirms)
+    - "No"
+
+On "Yes — auto-draft":
+  - Draft a 2-4 sentence prompt summarizing:
+    - What was just accomplished (from resolved items / recent changelog)
+    - What's next (first 1-2 sprint items with brief context)
+    - Any open design questions worth flagging
+  - Present draft, ask `AskUserQuestion` for confirmation:
+    - "Save this prompt? [Yes / Edit first / Skip]"
+
+On "Yes — I'll dictate": prompt user for free-text input.
+
+On "No": skip.
+
+### Step 6: Create handoff entry
+
+If prompt was provided, call:
+```
+mcp__dct__create_handoff(
+    project=<slug>,
+    prompt=<text>,
+    created_by=f"claude-{model_id} @ {project_slug} {isoformat_utc_now()}Z",
+    scope=<scope or "">,
+)
+```
+
+Remember the returned `id`.
+
+### Step 6b: CC task-list mirror cleanup (v0.4.0)
+
+If the TaskCreate mirror hook (`dct/hooks/dct-task-mirror.sh`) is active, the
+current session may have spawned a session-scoped item with checkpoints
+mirrored from TaskCreate/TodoWrite calls. These items have the tag
+`cc-task-list` and title `"CC task list — session <id>"`.
+
+Probe: `mcp__dct__list_items(project=<slug>)` filtered for `tags` containing
+`cc-task-list`. For each such item surface via `AskUserQuestion`:
+
+  question: f"Session item #{id} has N CC task-list checkpoints. What to do?"
+  header:   "CC task list"
+  options:
+    - "Resolve — the todos were one-off, archive it"
+      → `resolve_item(id, status="resolved", resolution="session ephemeral, archived on /handoff")`
+    - "Promote N checkpoints to real items"
+      → for each cc-task checkpoint: `promote_checkpoint_to_item` (or user picks subset)
+    - "Keep — I'll revisit next session"
+      → leave as-is; next session's /pickup will surface it
+    - "Skip"
+
+This keeps backlog clean — ephemeral harness-tasks don't accumulate as
+permanent items across months of sessions.
+
+### Step 7: Report
+
+```
+✓ Handoff #N zapisany
+  Sprint: 3 itemy (#22, #21, #6)
+  Scope: sprint-v0.2
+  Prompt: "Zacznij od #22..." (142 chars)
+
+Next session: /pickup
+```
+
+## Rules
+
+- **Every user decision is an `AskUserQuestion` call.** No plain-text prompts.
+- Never call `set_sprint` without user confirming the list.
+- Never write a handoff prompt without user confirming content.
+- `created_by` MUST be non-empty; include model id + project + UTC timestamp.
+- On `set_sprint`, if replacing a non-empty sprint, surface the diff ("removing: #7; adding: #22") in the confirmation question.

dct/skills/pickup/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: pickup
+description: |
+  Start-of-session workflow — read last session's handoff, show current sprint,
+  and propose the first action.
+  Use when: "pickup", "gdzie byliśmy", "resume", "where were we", "start session",
+  "co robimy", "kontynuuj", "podejmij od",
+  "co dalej", "kontynuujmy", "wracam", "jestem z powrotem",
+  "dalej", "idziemy dalej", "next up", "what's next", "back to work".
+---
+
+# /pickup — Session Resume
+
+Open a new session by loading the previous session's handoff prompt + current
+sprint state, then propose a concrete first action.
+
+## Workflow
+
+### Step 1: Detect project
+
+`mcp__dct__list_projects` → match CWD (longest prefix).
+If not registered, ask via `AskUserQuestion`:
+  - question: "Which project are we working on?"
+  - options: list of slugs + "Cancel"
+
+### Step 2: Fetch review
+
+Call `mcp__dct__review_sprint(project, since="last_release")`.
+
+Returns:
+- `in_sprint` — currently flagged items
+- `recent_activity` — items changed since anchor
+- `stale_in_progress` — forgotten in-progress items
+- `unconsumed_handoffs` — unread drafts from previous sessions
+
+### Step 3: Handle unconsumed handoffs
+
+**If there are 0 handoffs** — skip to Step 4.
+
+**If there is exactly 1 handoff**, present its prompt and ask via `AskUserQuestion`:
+  - question: "Handoff #N [scope: X] from <created_at> by <created_by>:\n\n<prompt>\n\nPick up this handoff?"
+  - options:
+    - "Yes — consume and follow it"
+    - "Yes — follow it but keep unconsumed (for audit)"
+    - "No — start fresh, discard this handoff"
+    - "Show other recent handoffs"
+
+**If there are multiple**, ask via `AskUserQuestion`:
+  - question: "N handoffs waiting. Which to pick up?"
+  - options: one per handoff formatted `#N [scope] — <first 80 chars of prompt>` + "None — start fresh"
+
+On picked handoff:
+- "Yes — consume" → `mcp__dct__consume_handoff(id, consumed_by=<session_id>)`
+- "keep unconsumed" → use prompt content, don't stamp consumed_at
+- "start fresh" → optionally ask to `delete_handoff(id)` (soft) or just leave
+
+### Step 4: Show sprint
+
+Present `in_sprint` as a compact table (use format from `review_sprint.in_sprint`).
+Show summary: sprint_size, sprint_completion, handoffs_pending.
+
+If sprint is empty BUT there are open items in the project, ask via `AskUserQuestion`:
+  - question: "Sprint is empty (but N items open). What next?"
+  - options:
+    - "Pick sprint items now — run /handoff style proposal"
+    - "Browse open items — /track-list"
+    - "Just start working — I'll tell you what"
+
+If sprint is empty AND there are NO open items in the project, ask via `AskUserQuestion`:
+  - question: "Project is empty — nothing to pick up. What now?"
+  - options:
+    - "Create the first item — run /track"
+    - "Import existing tracking data — run /dct-import"
+    - "Exit — not the right project"
+
+### Step 5: Propose first action
+
+Combine:
+- Handoff prompt (if consumed) — primary intent
+- First in_sprint item by priority — concrete entry point
+- Any stale_in_progress — optional "unstick first" path
+
+Present via `AskUserQuestion`:
+  - question: "First action for this session?"
+  - options:
+    - "Open #<first-sprint-item> and start on its checkpoints"
+    - "Review all sprint items first"
+    - "Look at stale in_progress first (#X)"
+    - "Something else — tell me what"
+
+### Step 6: Report and open context
+
+Based on user choice, run the matching action:
+- "Open #X" → `mcp__dct__get_item(X)` + show checkpoints as next-step plan
+- "Review all" → full sprint listing
+- "Stale first" → `mcp__dct__get_item(<stale>)`
+- "Something else" → wait for user input
+
+Report:
+```
+✓ Picked up handoff #N
+  Sprint: 3 items, 0/3 done
+  Starting: #22 — "Optimize MCP response format"
+  Plan: 4 pending checkpoints in this item
+```
+
+## Rules
+
+- **Every decision is an `AskUserQuestion`.** No plain-text Y/N prompts.
+- Don't auto-consume handoffs — user must approve (consume vs keep vs discard).
+- On empty sprint + no handoffs, don't force-create a sprint — ask user what to do.
+- Show resolved items from `review_sprint.recent_activity` only as context, not as
+  work candidates (they're done).
+- `consumed_by` should mirror `/handoff`'s `created_by` format:
+  `claude-<model_id> @ <project_slug> <iso_utc>Z`.

dct/skills/plan-resolve-uncertain/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: plan-resolve-uncertain
+description: |
+  Batch-resolve plan sections flagged `section_type='uncertain'` during
+  import. Offers LLM classification (via `claude --print`) per section or
+  manual override. Use when: "plan-resolve-uncertain", "resolve uncertain",
+  "sklasyfikuj niejasne", "check uncertain sections", "fix section types",
+  "uncertain sections", "classify plan sections".
+---
+
+# /plan-resolve-uncertain — Classify Uncertain Plan Sections
+
+## When to invoke
+
+- After `/dct-import` reported `uncertain_remaining > 0`.
+- `/pickup` surfaces uncertain sections and user accepts the follow-up.
+- User explicitly asks to review / fix uncertain classifications.
+
+## Workflow
+
+### Step 1: Resolve project
+
+Auto-detect from CWD. Confirm via `AskUserQuestion` if ambiguous.
+
+### Step 2: List uncertain sections
+
+Use `mcp__dct__list_plan_sections(plan_id=X, ...)` with `section_type="uncertain"`
+for each active plan, OR construct a direct query via the CLI
+(`dct plan resolve-uncertain --dry-run` if available).
+
+Present a compact table:
+```
+plan               depth  heading
+─────────────────  ─────  ─────────────────────────────────────
+v0.2-impl          2      Phase 0 — Shared foundations
+v0.2-impl          3      Open questions for v0.2.1
+roadmap            2      Amendments to Spec
+```
+
+### Step 3: Strategy choice
+
+`AskUserQuestion`:
+- "N uncertain sections. How to resolve?"
+- Options:
+  - "Auto-classify all via Claude Haiku (≈ $0.001/each)" — default if user is OK with LLM cost
+  - "Review one-by-one (manual decision per section)"
+  - "Mark all as 'prose' (safe default for narrative sections)"
+  - "Skip — leave as uncertain"
+
+### Step 4a: Auto-classify
+
+For each section:
+- Call the classifier indirectly via `dct plan rescan <file> --resolve-uncertain`
+  OR invoke `classify_uncertain()` equivalent.
+- On result: update via `mcp__dct__add_plan_section` isn't right (section exists);
+  use a targeted update path: an MCP helper not yet exposed — fall back to
+  manual `dct plan set-section-type <ulid> <type>` CLI if present.
+- Aggregate: how many resolved, how many still uncertain.
+
+### Step 4b: Review one-by-one
+
+Per section, `AskUserQuestion`:
+- Question: "Section `<heading>` — what type?"
+- Options: sprint, phase, task, block, milestone, decision, prose, changelog,
+  adr_section, reference, generic, (skip).
+- Apply choice.
+
+### Step 4c: Mark all as prose
+
+Blanket update — quick escape hatch when user has read through them and
+concluded they are all narrative text.
+
+### Step 5: Report
+
+`"Resolved N, remaining M uncertain. Review next session via /plan-status."`
+
+## Rules
+
+- Never silently accept LLM output without user approval at the strategy step.
+- Cost-aware — report estimated LLM cost upfront before running batch.
+- Graceful fallback if `claude` CLI missing — fall back to manual mode.
+- Idempotent — re-running the skill on already-resolved sections is a no-op.

dct/skills/plan-status/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: plan-status
+description: |
+  Cross-plan progress dashboard for a project. Shows per-plan done/total
+  checkpoint counts, uncertain section count, and last-scanned timestamp.
+  Use when: "plan-status", "plan progress", "pokaż plany", "co zostało
+  w planach", "ile zrobione w planie X", "status planów", "how much of
+  the plan is done", "stan planów".
+---
+
+# /plan-status — Cross-plan Progress Dashboard
+
+## When to invoke
+
+- User asks about progress across plans in the current project.
+- Session start / handoff — show high-level plan health alongside sprint review.
+- Before making planning decisions (pick a plan with most pending work, etc.).
+
+## Workflow
+
+### Step 1: Resolve project
+
+Auto-detect from CWD via `mcp__dct__list_projects()` + longest-prefix match.
+If not registered, ask via `AskUserQuestion`.
+
+### Step 2: Fetch plans
+
+`mcp__dct__list_plans(project=<slug>, status="active")` — returns `{cols, rows}`.
+
+### Step 3: Enrich each plan with progress
+
+For each plan row, call `mcp__dct__get_plan(plan_id)` to get the `progress`
+sub-dict and sections needing review.
+
+### Step 4: Render table
+
+```
+#   kind    status  progress  uncertain  last-scanned  title
+──  ──────  ──────  ────────  ─────────  ────────────  ─────────────────────
+12  plan    active  8/10      2          2026-04-17    Plans/roadmaps schema
+17  spec    active  3/3       0          2026-04-15    …
+23  adr     active  —         0          2026-04-10    ADR-001: Use ULIDs
+```
+
+`progress` format:
+- Plans with checkpoints: `done/active` (rejected excluded).
+- Plans with only sections and no checkpoints (specs, ADRs): show `—`.
+
+`uncertain`: count of `plan_sections.needs_llm_review=TRUE`.
+
+### Step 5: Optional drill-down
+
+Ask via `AskUserQuestion`:
+- "Show details for a specific plan?"
+- Options: one per plan (`#12 — Plans/roadmaps schema`), or "Done".
+- On selection: `mcp__dct__get_plan(id)` full dump + structured section tree.
+
+## Rules
+
+- Read-only — never modify plans / sections / checkpoints from this skill.
+- Respect `format="structured"` default — pretty-print only at the final
+  rendering step, not in the MCP calls themselves.
+- When no plans exist, emit a one-liner (`"No plans registered in <project>"`)
+  and stop — do not suggest creating one unprompted.
+
+## Example dialog
+
+> User: "/plan-status"
+>
+> Claude:
+>   Project: dct (detected from CWD)
+>   Plans: 3 active, 0 completed, 0 archived.
+>
+>   #   kind   status  progress  uncertain  last-scanned  title
+>   ── ─────  ──────  ────────  ─────────  ────────────  ─────
+>   12  plan   active  6/10      0          2026-04-17    v0.2.0 implementation
+>   ...
+>
+>   Any plan to drill into?