@groupby/ai-dev 0.2.1 → 0.3.0

package/skills/library/implementation-plan/SKILL.md

@@ -0,0 +1,337 @@
+---
+name: implementation-plan
+description: >-
+  Generate a structured implementation plan from a source document, inline notes,
+  or any written input. Use when starting a new feature, task, or project and you
+  need a phased breakdown with checklists, detailed sub-plans, and architecture
+  justification. Produces planning files in docs/planning/.
+---
+
+# Implementation Plan
+
+Turn a source document or set of notes into a structured, actionable implementation plan with phased checklists.
+
+## Input
+
+The user provides **one** of:
+
+- A path to an existing document (spec, ticket export, design doc, etc.)
+- Inline notes or a description pasted into the conversation
+- Any other written source of requirements
+
+## Process
+
+### 1. Read and understand the source material
+
+- If the user provided a file path, read the file.
+- If the user provided inline notes, use those directly.
+- Extract the following from the source material:
+  - **Goal and scope** — what is being done and what is explicitly out of scope
+  - **Acceptance criteria** — concrete conditions for "done," if stated
+  - **Decisions already made** — explicit choices from the source, with rationale if available
+  - **Assumptions** — things taken as true that haven't been verified; note confidence (high/medium/low) where possible
+  - **Open questions** — unresolved items that could affect the plan
+  - **Risks** — things that could go wrong or are uncertain
+  - **Dependencies** — other work, people, or systems this depends on
+
+### 2. Read the architecture docs
+
+Read the project's architecture documentation at `docs/architecture/`. At minimum scan the README and any file relevant to the task. Use these docs to:
+
+- Understand existing conventions, patterns, and structure.
+- Justify the approaches taken in the plan.
+- Identify which existing code, modules, or patterns the implementation should follow or extend.
+
+If `docs/architecture/` does not exist or is empty, note this and proceed with whatever project context is available.
+
+Also scan `docs/planning/` for related existing plans. If the new plan relates to or supersedes an existing one, note it in the Source section.
+
+### 3. Determine plan scope
+
+Assess the size and complexity of the work:
+
+- **Small scope** (1–3 discrete tasks, single concern): produce a **single planning file**.
+- **Larger scope** (4+ tasks, multiple concerns, or cross-cutting changes): produce a **planning folder** with a top-level README, clarifications, and a `plan/` sub-folder containing the core planning doc and individual sub-plan files.
+
+### 4. Choose a story name
+
+The output location is `docs/planning/<story-name>/` (folder) or `docs/planning/<story-name>.md` (single file).
+
+Determine the story name:
+
+- If the source is a Jira ticket, use the ticket key in lowercase (e.g. `bs-734`).
+- Otherwise, create a short, lowercase, kebab-case name that describes the work (e.g. `configurable-install-path`, `auth-refactor`).
+
+Ask the user to confirm the story name before writing files, unless it is obvious from context.
+
+### 5. Generate clarifications
+
+Produce a `clarifications.md` file that identifies ambiguities in the source material and answers each one with a reasonable assumption. Write it as a sibling to the plan output:
+
+- **Single-file plans:** `docs/planning/<story-name>-clarifications.md`
+- **Folder plans:** `docs/planning/<story-name>/clarifications.md`
+
+See the **Clarifications Format** section below for the template.
+
+**IMPORTANT: Do not stop after writing clarifications. Immediately proceed to Step 6 and generate the full plan in the same pass.** The clarifications file is a reference artifact, not a gate. The plan is always the primary output.
+
+The assumptions from clarifications feed directly into the plan. Every assumption made in clarifications should be reflected in the plan's Decisions or Assumptions sections. If the user later disagrees with an assumption, they can edit the `ANSWER:` lines in clarifications and ask for the plan to be regenerated.
+
+### 6. Write the plan
+
+Follow the appropriate format below. Incorporate the clarifications — the plan should be written as though the assumptions are settled unless the user overrode them.
+
+---
+
+## Clarifications Format
+
+```markdown
+# Clarifications: <Title>
+
+Ambiguities and assumptions identified before planning. Each item includes a
+question and an assumed answer. Override any answer by editing the `ANSWER:`
+line and asking for the plan to be updated.
+
+---
+
+### 1. <Short question title>
+
+<Context: why this is ambiguous or could go multiple ways.>
+
+ANSWER: <Assumed answer with brief reasoning.>
+
+---
+
+### 2. <Short question title>
+
+<Context.>
+
+ANSWER: <Assumed answer.>
+
+---
+
+...
+```
+
+---
+
+## Output Format: Single File
+
+Use when scope is small (1–3 tasks). Write to `docs/planning/<story-name>.md`.
+
+Structure:
+
+```markdown
+# <Title>
+
+<One-paragraph summary of what this plan accomplishes and why.>
+
+## Source
+
+<Link to the original document if it exists, OR include the original notes/prompt below. If this plan relates to or supersedes an existing plan, note that here.>
+
+## Architecture context
+
+<Brief summary of relevant architecture decisions, conventions, or patterns from docs/architecture/ that inform this plan. Cite specific files.>
+
+## Decisions
+
+<Decisions made during planning that shaped the approach. For each: what was decided and why. Include decisions inherited from clarifications.>
+
+## Open questions
+
+<Unresolved items that could not be assumed away. For each: the question, who might answer it, and what the plan assumes in the meantime.>
+
+## Implementation checklist
+
+- [ ] Task 1 — brief description
+- [ ] Task 2 — brief description
+- [ ] ...
+- [ ] Update or create documentation if needed
+- [ ] Add/update tests
+- [ ] Manual review: <describe what to verify>
+
+## Detail
+
+### Task 1
+
+<Full detail: what to change, where, why, edge cases, references to architecture docs.>
+
+### Task 2
+
+...
+
+## Next steps
+
+<2–3 brief suggestions for what to do after the plan is complete: share for review, create Jira tickets, start implementing a specific task, etc.>
+```
+
+---
+
+## Output Format: Planning Folder
+
+Use when scope is larger (4+ tasks or multiple concerns). Write to `docs/planning/<story-name>/`.
+
+### Required folder structure
+
+The plan **must** live in its own `plan/` sub-folder. Top-level files are for context and metadata only. Sub-plan files never go at the top level.
+
+```
+docs/planning/<story-name>/
+    README.md             # Overall intent, notes, links to plan elements
+    clarifications.md     # Ambiguities and assumed answers (see format above)
+    plan/
+        README.md         # Core planning doc — decisions, checklist, links to sub-plans
+        <sub-plan-1>.md
+        <sub-plan-2>.md
+        …
+        <sub-plan-n>.md
+```
+
+### Top-level README.md
+
+A lightweight overview of what this planning effort is about. It captures intent and source material, and links into the plan folder for details.
+
+```markdown
+# <Title>
+
+<One-paragraph summary of the overall goal — what is being done and why.>
+
+## Source
+
+<Link to the original document, OR include the original notes/prompt. The original intent MUST be captured in this file. If this plan relates to or supersedes an existing plan, note that here.>
+
+## Contents
+
+- [Clarifications](./clarifications.md) — ambiguities and assumed answers
+- [Plan](./plan/) — implementation plan and sub-plans
+```
+
+### plan/README.md
+
+The core planning document. Contains architecture context, decisions, the plan checklist, and review criteria. All links to sub-plans point to sibling files within `plan/`.
+
+```markdown
+# <Title>
+
+<One-paragraph summary of what this plan accomplishes and why.>
+
+## Plan
+
+- [ ] [Sub-plan title](./sub-plan-name.md)
+- [ ] [Sub-plan title](./another-sub-plan.md)
+- [ ] ...
+
+## Source
+
+<Link or reference back to the top-level README or the original document.>
+
+## Architecture context
+
+<Brief summary of relevant conventions and patterns from docs/architecture/. Cite specific files.>
+
+## Decisions
+
+<Key decisions that cut across sub-plans. For each: what was decided and why. Sub-plan-specific decisions belong in their respective files.>
+
+## Open questions
+
+<Unresolved items that could affect multiple sub-plans.>
+
+## Manual review
+
+<If applicable, describe what needs to be manually confirmed after all sub-plans are complete. If each sub-plan has its own review step, state that here instead.>
+
+## Next steps
+
+<2–3 brief suggestions for what to do after the plan is complete.>
+```
+
+### Individual sub-plan files (in plan/)
+
+Each file lives inside `plan/` and is a self-contained planning document. Use lowercase kebab-case filenames (e.g. `api-endpoints.md`, `database-migration.md`).
+
+Structure:
+
+```markdown
+# <Sub-plan Title>
+
+<One-paragraph summary of what this sub-plan covers and its goal.>
+
+## Context
+
+<Everything needed to execute this sub-plan WITHOUT reading other sub-plan files. Include:>
+- Relevant architecture decisions (cite docs/architecture/ files)
+- Background from the source material
+- Any dependencies on other sub-plans (link for additional context, but include enough detail here to proceed independently)
+
+## Assumptions
+
+<What this sub-plan takes as given. Include confidence level where it's not obvious. Sourced from clarifications and architecture docs.>
+
+## Risks
+
+<What could go wrong. For each: likelihood, impact, and mitigation.>
+
+## Phases
+
+### Phase 1 — <Name>
+
+- [ ] Step description
+- [ ] Step description
+
+### Phase 2 — <Name>
+
+- [ ] Step description
+- [ ] ...
+
+<Use as many phases as appropriate. Single-phase sub-plans are fine for small pieces of work.>
+
+## Detail
+
+<Expand on each step. Provide:>
+- Exact files to create or modify
+- Code patterns to follow (referencing architecture docs)
+- Edge cases and risks
+- Test requirements (what to test, where test files should live)
+- Documentation to create or update
+
+## Review
+
+<What to verify after this sub-plan is complete. Specific outputs, behaviors, or states to confirm.>
+```
+
+---
+
+## Principles
+
+1. **Clarify and plan in one pass.** Generate clarifications first, then immediately produce the full plan based on those assumptions. Never stop after clarifications — the plan is the primary output.
+
+2. **Self-sufficiency.** Each sub-plan file must be independently actionable. A developer (or agent) should be able to pick up any single file and execute it without cross-referencing other sub-plans.
+
+3. **Architecture grounding.** Every approach must be justified by the project's architecture docs. If the architecture docs don't cover a relevant area, say so explicitly and state the reasoning.
+
+4. **Phased execution.** For non-trivial sub-plans, break work into phases. This enables incremental progress and natural review points.
+
+5. **Completeness.** Plans must account for:
+   - Implementation (the core work)
+   - Tests (unit, integration, or end-to-end as appropriate)
+   - Documentation (new docs or updates to existing docs)
+   - Manual review (what a human should verify at the end)
+
+6. **Traceability.** The README must always capture or link to the original source material so the intent behind the plan is never lost.
+
+7. **Minimal overhead.** Don't over-plan simple tasks. A 2-step task does not need a folder with sub-plans — a single file with a checklist is sufficient.
+
+8. **Follow-up awareness.** After writing the plan, briefly suggest what comes next. Keep it to 2–3 bullet points — don't prescribe a workflow.
+
+---
+
+## Edge Cases
+
+- **No architecture docs found:** Proceed without architecture grounding. Note the gap in the plan and suggest creating architecture docs as a follow-up.
+- **Ambiguous scope:** Default to a planning folder. It's easier to consolidate later than to split a monolithic file.
+- **Source is a conversation or verbal description:** Capture the full description in the README's Source section verbatim, then plan from it.
+- **Overlapping concerns between sub-plans:** Duplicate the relevant context into both files rather than creating cross-references. Self-sufficiency is more important than avoiding repetition.
+- **User wants to skip clarifications:** Respect this. Generate the plan directly, but still surface assumptions inline in the Decisions and Assumptions sections.
+- **User disagrees with clarifications after the plan is written:** Read the `ANSWER:` lines in the clarifications file, then regenerate the plan incorporating the revised assumptions.

package/skills/library/jira-plan/README.md

@@ -0,0 +1,17 @@
+# jira-plan
+
+Generate an implementation plan starting from a Jira ticket. Fetches the full ticket context — epic hierarchy, acceptance criteria, subtasks, linked issues, and recent comments — then delegates to [`implementation-plan`](../implementation-plan/) for the actual plan generation.
+
+## Requirements
+
+Requires Atlassian MCP (`atlassian-rovo`). Without it, use `implementation-plan` directly.
+
+## Example prompts
+
+- `/jira-plan PROJ-123`
+- "Plan the implementation for BS-734"
+- "Create a plan from ticket PROJ-456"
+
+## Related
+
+- [`implementation-plan`](../implementation-plan/) — the core planning skill this wraps; use directly when you don't have a Jira ticket

package/skills/library/jira-plan/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: jira-plan
+description: >-
+  Generate an implementation plan from a Jira ticket. Fetches the full ticket
+  context — epic hierarchy, acceptance criteria, subtasks, linked issues, and
+  recent comments — then delegates to the implementation-plan skill for phased
+  checklist generation. Use when you want to plan work starting from a Jira
+  ticket key. Requires Atlassian MCP.
+---
+
+# Jira Plan
+
+Fetch a Jira ticket's full context and produce a structured implementation plan using the `implementation-plan` skill.
+
+## Requirements
+
+Requires: Atlassian MCP (`atlassian-rovo`). If Atlassian MCP is not available, tell the user and suggest using `implementation-plan` directly with the ticket details pasted manually.
+
+## Input
+
+The user provides a **Jira ticket key** (e.g. `PROJ-123`).
+
+Optionally, the user may also provide:
+
+- Additional context or constraints not captured in the ticket
+- A preferred story name (otherwise defaults to the ticket key in lowercase)
+
+## Process
+
+### 1. Resolve the ticket key
+
+- If the user provides a full key (e.g. `PROJ-123`), use it directly.
+- If the user provides just a number and a project key is available from context (git branch pattern, config file, or prior conversation), prepend it.
+- If the key cannot be resolved, ask the user for the full ticket key.
+
+### 2. Fetch ticket details
+
+Use `mcp_atlassian-rovo_fetch()` to retrieve:
+
+- **Summary and description**
+- **Acceptance criteria** (often in the description or a custom field)
+- **Status, assignee, priority, story points**
+- **Subtasks** — fetch via JQL: `parent = {TICKET-KEY} ORDER BY status ASC, priority DESC`
+- **Linked issues** — blocks, is blocked by, relates to
+- **Recent comments** — last 5–10 comments (these often contain decisions and clarifications not in the description)
+
+### 3. Fetch parent epic context
+
+Detect the parent epic:
+
+1. Check `fields.parent` — if `parent.fields.issuetype.name == "Epic"`, that is the epic.
+2. Check for an Epic Link custom field (varies by instance; commonly `customfield_10014` or similar).
+
+If an epic is found, fetch:
+
+- Epic summary, description, and goals
+- Sibling stories via JQL: `"Epic Link" = {EPIC-KEY} AND key != {TICKET-KEY} ORDER BY status ASC, priority DESC`
+
+Sibling context helps scope the plan — it reveals what's already being done in the epic and what this ticket's boundaries are.
+
+If no epic is found, note the ticket is orphaned and proceed.
+
+### 4. Fetch linked Confluence pages (optional)
+
+If the ticket or epic has linked Confluence pages (remote links), fetch their titles and brief summaries. These often contain requirements, architecture decisions, or design docs relevant to planning.
+
+### 5. Assemble structured context
+
+Combine all fetched information into a structured context document. This becomes the input to `implementation-plan`.
+
+Format the assembled context as:
+
+```markdown
+# {TICKET-KEY}: {Summary}
+
+## Ticket details
+
+- **Status:** {status}
+- **Assignee:** {assignee or "Unassigned"}
+- **Priority:** {priority}
+- **Points:** {story_points or "Not estimated"}
+
+## Description
+
+{Full ticket description}
+
+## Acceptance criteria
+
+{Acceptance criteria extracted from the ticket. If embedded in the description, extract and list them. If in a custom field, use that.}
+
+- [ ] {criterion 1}
+- [ ] {criterion 2}
+- ...
+
+## Subtasks
+
+{If subtasks exist:}
+| Key | Summary | Status |
+|-----|---------|--------|
+| {KEY} | {summary} | {status} |
+
+{If no subtasks: "None"}
+
+## Linked issues
+
+{For each linked issue:}
+- **{link type}** {KEY}: {summary} ({status})
+
+{If none: "None"}
+
+## Epic context
+
+{If epic found:}
+**{EPIC-KEY}: {Epic summary}**
+
+{Epic description excerpt — first 2-3 paragraphs}
+
+### Sibling stories
+| Key | Summary | Status | Assignee |
+|-----|---------|--------|----------|
+| {KEY} | {summary} | {status} | {assignee} |
+
+{If no epic: "No parent epic found (orphaned ticket)."}
+
+## Recent comments
+
+{Last 5-10 comments, most recent first:}
+**{author}** ({date}):
+> {comment body, truncated to first paragraph if very long}
+
+{If no comments: "None"}
+
+## Linked documentation
+
+{If Confluence pages found:}
+- {Page title} — {space key}
+
+{If none: "None"}
+```
+
+### 6. Delegate to `implementation-plan`
+
+Pass the assembled context to the `implementation-plan` skill. Follow that skill's full process starting from **Step 2** (Read the architecture docs):
+
+- The assembled context above is the "source material" for Step 1.
+- The story name defaults to the ticket key in lowercase (e.g. `proj-123`) unless the user specified otherwise.
+- All output formats, clarifications, phased checklists, and principles from `implementation-plan` apply.
+
+### 7. Add Jira-specific next steps
+
+After the plan is generated, append Jira-relevant suggestions to the Next Steps section:
+
+- "Update the Jira ticket status to In Progress when starting implementation"
+- "Add a comment to the ticket linking to this plan: `docs/planning/<story-name>/`"
+- "Create subtasks in Jira for each sub-plan if the team tracks at that level"
+
+## Edge Cases
+
+- **Atlassian MCP unavailable:** Do not attempt to fetch. Inform the user and suggest using `implementation-plan` directly.
+- **Ticket not found or inaccessible:** Report the error clearly. The ticket may have been moved, deleted, or be in a project the user can't access.
+- **Very large epic (20+ stories):** Summarize sibling stories rather than listing all of them. Focus on in-progress and to-do stories.
+- **Ticket has no description:** Proceed with just the summary, acceptance criteria, and comments. Note the gap in clarifications.
+- **Comments contain conflicting decisions:** Surface these as questions in the clarifications file.

package/toolsets/rzlv-flow/README.md

@@ -4,20 +4,41 @@ A toolset of modular, composable skills for Jira and Confluence developer workfl
 
 Each skill is standalone and can be installed individually or as a complete suite.
 
+## Quick Start
+
+```bash
+# 1. Install all skills + resources
+npx @groupby/ai-dev install toolset rzlv-flow
+
+# 2. Configure Atlassian MCP (see docs/mcp-setup.md)
+#    Add atlassian-rovo config to .vscode/mcp.json
+
+# 3. Use — ask your AI assistant:
+#    "Start my day"           → daily triage
+#    "Focus on PROJ-123"      → ticket deep-dive
+#    "Wrap up PROJ-123"       → wrap & sync
+```
+
+See [docs/getting-started.md](docs/getting-started.md) for a full walkthrough.
+
 ## Skills
 
 | Skill | Description | Status |
 |-------|-------------|--------|
-| `jira-daily-triage` | Start-of-day ticket triage with sprint detection | Planned |
-| `jira-ticket-focus` | Deep-load a ticket with full context | Planned |
-| `jira-wrap-sync` | Wrap up work, draft comment, multi-action sync | Planned |
-| `jira-ticket-trace` | Trace code back to Jira requirements | Planned |
-| `jira-comment` | Add a comment to a Jira ticket with FCMP safety | Planned |
-| `jira-status` | Change ticket status with transition validation | Planned |
-| `jira-sprint-status` | Sprint status report with completion metrics | Planned |
-| `jira-sync` | Force-sync local Jira context with remote state | Planned |
+| `jira-daily-triage` | Start-of-day ticket triage with sprint detection | Complete |
+| `jira-ticket-focus` | Deep-load a ticket with full context | Complete |
+| `jira-wrap-sync` | Wrap up work, draft comment, multi-action sync | Complete |
+| `jira-ticket-trace` | Trace code back to Jira requirements | Complete |
+| `jira-comment` | Add a comment to a Jira ticket with FCMP safety | Complete |
+| `jira-status` | Change ticket status with transition validation | Complete |
+| `jira-sprint-status` | Sprint status report with completion metrics | Complete |
+| `jira-sync` | Force-sync local Jira context with remote state | Complete |
 | `atlassian-orchestrator` | Pull surrounding ticket context and create structures | Complete |
 | `context-analyst` | Transform meeting transcripts into structured docs | Complete |
+| `confluence-publish` | Publish local markdown to Confluence with Leaf Bundle mirrors | Complete |
+| `confluence-fetch` | Pull a Confluence page into a local markdown mirror | Complete |
+
+> **Note:** `confluence-publish` provides lightweight ad-hoc publishing to Confluence. For bulk structured sync of `_docs/` folders following epic hierarchy, use `atlassian-orchestrator` Mode 3 instead.
 
 ## Prerequisites
 
@@ -38,7 +59,16 @@ npx @groupby/ai-dev install toolset rzlv-flow       # All skills + resources
 npx @groupby/ai-dev install skill jira-daily-triage   # Individual skill
 ```
 
-> **Note:** CLI toolset support is coming soon. For now, skills can be copied manually from this repository into your project's `docs/ai/skills/` directory, and resources into `docs/ai/resources/`.
+Common options:
+
+| Flag | Description |
+|------|-------------|
+| `--target <dir>` | Install into a specific directory (defaults to cwd) |
+| `--dry-run` | Preview what would be installed without writing files |
+| `--force` | Overwrite existing files without prompting |
+| `--skip-existing` | Skip files that already exist |
+
+You can also copy skills manually from this repository into `docs/ai/skills/` and resources into `docs/ai/resources/`.
 
 ## BMAD Compatibility
 
@@ -55,3 +85,18 @@ Skills reference shared resource files installed to `docs/ai/resources/` in your
 | `confluence-file-structure.md` | Leaf Bundle pattern for Confluence page mirrors |
 | `sync-state-format.md` | YAML frontmatter schema for ticket and page files |
 | `confluence-page-templates/` | Starter scaffolds for Confluence pages (initiative overview, strategic context, technical architecture, decisions) |
+
+## MCP Setup Automation
+
+MCP server configuration is currently manual — see [docs/mcp-setup.md](docs/mcp-setup.md) for step-by-step instructions (~5 minutes). Automated MCP configuration via the CLI is a future enhancement.
+
+## Documentation
+
+| Doc | Description |
+|-----|-------------|
+| [docs/getting-started.md](docs/getting-started.md) | Quick walkthrough: install → configure → use |
+| [docs/mcp-setup.md](docs/mcp-setup.md) | Atlassian and GitHub MCP server configuration |
+
+## Contributing
+
+See the [architecture documentation](../../docs/architecture/README.md) for repo structure, skill authoring guides, and conventions.