@chorus-aidlc/chorus-openclaw-plugin 0.3.0 → 0.4.0

package/skills/proposal/SKILL.md

@@ -0,0 +1,399 @@
+---
+name: proposal
+description: Chorus Proposal workflow — create proposals with document & task drafts, manage DAG, submit for review.
+metadata:
+  openclaw:
+    emoji: "📋"
+---
+
+# Proposal Skill
+
+This skill covers the **Planning** stage of the AI-DLC workflow: creating Proposals that contain document drafts (PRD, tech design) and task drafts with dependency DAGs, then submitting them for Admin review.
+
+---
+
+## Overview
+
+After an Idea's elaboration is resolved (see `/idea`), the PM Agent creates a Proposal — a container that holds document drafts and task drafts. On Admin approval, these drafts materialize into real Documents and Tasks.
+
+```
+Elaboration resolved --> Create Proposal --> Add drafts --> Validate --> Submit --> Admin review
+```
+
+### Proposal Lifecycle
+
+```
+draft --> pending --> approved
+                \--> rejected --> (revise drafts) --> pending  (resubmit cycle)
+```
+
+| Status | Meaning |
+|--------|---------|
+| `draft` | Proposal is being built — add/edit document and task drafts |
+| `pending` | Submitted for Admin review |
+| `approved` | Admin approved — drafts materialized into real Documents and Tasks |
+| `rejected` | Admin rejected with feedback — revise drafts and resubmit |
+
+A rejected proposal returns to `draft` status. Fix issues based on the review note, then validate and resubmit.
+
+---
+
+## Tools
+
+**Proposal Management:**
+
+| Tool | Purpose |
+|------|---------|
+| `chorus_create_proposal` | Create an empty proposal container linked to input ideas |
+| `chorus_get_proposal` | Get full proposal details including all document and task drafts |
+| `chorus_validate_proposal` | Validate proposal completeness (returns errors, warnings, info) |
+| `chorus_submit_proposal` | Submit proposal for Admin approval (draft -> pending) |
+
+**Document Drafts:**
+
+| Tool | Purpose |
+|------|---------|
+| `chorus_add_document_draft` | Add a document draft to the proposal |
+| `chorus_update_document_draft` | Update document draft title, type, or content |
+| `chorus_remove_document_draft` | Remove a document draft from the proposal |
+
+**Task Drafts:**
+
+| Tool | Purpose |
+|------|---------|
+| `chorus_add_task_draft` | Add a task draft (returns draftUuid for dependency chaining) |
+| `chorus_update_task_draft` | Update task draft fields or dependencies |
+| `chorus_remove_task_draft` | Remove a task draft from the proposal |
+
+**Post-Approval (tasks exist):**
+
+| Tool | Purpose |
+|------|---------|
+| `chorus_create_tasks` | Batch create tasks with intra-batch dependencies (also supports Quick Task mode) |
+| `chorus_update_task` | Update task fields, dependencies, or status |
+| `chorus_pm_assign_task` | Assign a task to a Developer Agent |
+
+**Shared tools** (checkin, query, comment, search, notifications): see `/chorus`
+
+---
+
+## SSE Wake Events (OpenClaw-Specific)
+
+OpenClaw is a single-agent model with SSE-driven wake. The following notification events trigger the agent to wake and act on proposals:
+
+| SSE Event | Trigger | Agent Action |
+|-----------|---------|--------------|
+| `proposal_rejected` | Admin rejected your proposal | Wake, read review note, revise drafts, resubmit |
+| `proposal_approved` | Admin approved your proposal | Wake, update idea status, check new tasks ready for work |
+
+When a proposal is rejected, the event router provides the review note and instructs the agent to fix issues. When approved, it notifies that documents and tasks have been created.
+
+---
+
+## Workflow
+
+### Step 1: Create an Empty Proposal
+
+Create the proposal container first, then incrementally add drafts.
+
+```
+chorus_create_proposal({
+  projectUuid: "<project-uuid>",
+  title: "Implement <feature name>",
+  description: "Analysis and implementation plan for Idea #xxx",
+  inputType: "idea",
+  inputUuids: ["<idea-uuid>"]
+})
+```
+
+**Multiple Ideas:** You can combine multiple ideas into one proposal by passing multiple UUIDs in `inputUuids`.
+
+### Step 2: Add Document Drafts
+
+Add document drafts one at a time.
+
+**Document types:** `prd`, `tech_design`, `adr`, `spec`, `guide`
+
+```
+# Add PRD
+chorus_add_document_draft({
+  proposalUuid: "<proposal-uuid>",
+  type: "prd",
+  title: "PRD: <Feature Name>",
+  content: "# PRD: <Feature Name>\n\n## Background\n...\n## Requirements\n..."
+})
+
+# Add Tech Design
+chorus_add_document_draft({
+  proposalUuid: "<proposal-uuid>",
+  type: "tech_design",
+  title: "Tech Design: <Feature Name>",
+  content: "# Technical Design\n\n## Architecture\n...\n## Implementation\n..."
+})
+```
+
+#### Document Type Guidelines
+
+| Type | Focus | When to Use |
+|------|-------|-------------|
+| `prd` | What and why — requirements, user stories, scope | Every feature proposal |
+| `tech_design` | How — architecture, data model, API design | Features with non-trivial implementation |
+| `adr` | Architecture Decision Record — decision context, options, outcome | Significant architectural choices |
+| `spec` | Detailed specification — protocols, formats, interfaces | API contracts, data formats |
+| `guide` | How-to guide — setup, usage, runbooks | Operational procedures |
+
+### Step 3: Add Task Drafts with Dependency DAG
+
+Add task drafts one at a time. Each response returns the new draft's `draftUuid` — use it in `dependsOnDraftUuids` for subsequent drafts to build the dependency DAG.
+
+```
+# First task (no dependencies) -> response includes { draftUuid, draftTitle }
+chorus_add_task_draft({
+  proposalUuid: "<proposal-uuid>",
+  title: "Create database schema",
+  description: "Add new tables for ...",
+  priority: "high",
+  storyPoints: 2,
+  acceptanceCriteriaItems: [
+    { description: "Migration runs without errors", required: true },
+    { description: "Rollback migration works", required: true }
+  ]
+})
+
+# Second task — depends on first
+chorus_add_task_draft({
+  proposalUuid: "<proposal-uuid>",
+  title: "Implement API endpoints",
+  description: "REST endpoints for ...",
+  priority: "high",
+  storyPoints: 4,
+  acceptanceCriteriaItems: [
+    { description: "All endpoints return correct responses", required: true },
+    { description: "Input validation covers edge cases", required: true },
+    { description: "OpenAPI spec updated", required: false }
+  ],
+  dependsOnDraftUuids: ["<draftUuid-from-first-task>"]
+})
+
+# Third task — depends on second
+chorus_add_task_draft({
+  proposalUuid: "<proposal-uuid>",
+  title: "Write integration tests",
+  description: "End-to-end tests covering ...",
+  priority: "medium",
+  storyPoints: 2,
+  acceptanceCriteriaItems: [
+    { description: "Test coverage > 80%", required: true }
+  ],
+  dependsOnDraftUuids: ["<draftUuid-from-second-task>"]
+})
+```
+
+**Task priority:** `low`, `medium`, `high`
+
+**Dependency DAG rules:**
+- `dependsOnDraftUuids` references other task drafts *within the same proposal*
+- Dependencies form a Directed Acyclic Graph (DAG) — no circular dependencies allowed
+- Tasks without dependencies are assumed parallelizable
+- On approval, draft dependencies become real task dependencies
+
+### Step 4: Review and Refine Drafts
+
+```
+# Review current state
+chorus_get_proposal({ proposalUuid: "<proposal-uuid>" })
+
+# Update a document draft
+chorus_update_document_draft({
+  proposalUuid: "<proposal-uuid>",
+  draftUuid: "<draft-uuid>",
+  content: "Updated content..."
+})
+
+# Update a task draft (including changing dependencies)
+chorus_update_task_draft({
+  proposalUuid: "<proposal-uuid>",
+  draftUuid: "<draft-uuid>",
+  description: "Updated description...",
+  dependsOnDraftUuids: ["<other-draft-uuid>"]
+})
+
+# Remove a draft that is no longer needed
+chorus_remove_task_draft({
+  proposalUuid: "<proposal-uuid>",
+  draftUuid: "<draft-uuid>"
+})
+```
+
+### Step 5: Validate and Submit
+
+**Always validate before submitting.** Validation catches errors that would block approval.
+
+```
+chorus_validate_proposal({ proposalUuid: "<proposal-uuid>" })
+```
+
+Returns `{ valid, issues }` where issues have levels:
+- **error** — Must fix before submitting (e.g., missing required fields, circular dependencies)
+- **warning** — Should fix but won't block submission (e.g., missing story points)
+- **info** — Suggestions (e.g., consider adding acceptance criteria)
+
+When validation passes (no errors):
+
+```
+chorus_submit_proposal({ proposalUuid: "<proposal-uuid>" })
+```
+
+This changes the status from `draft` to `pending`. An Admin will review it.
+
+Add a comment explaining your reasoning:
+
+```
+chorus_add_comment({
+  targetType: "proposal",
+  targetUuid: "<proposal-uuid>",
+  content: "This proposal addresses Idea #xxx. Key decisions: ..."
+})
+```
+
+### Step 6: Handle Rejection (SSE-Driven)
+
+If the proposal is rejected, the `proposal_rejected` SSE event wakes the agent with the review note. To handle:
+
+1. **Read the feedback:**
+   ```
+   chorus_get_proposal({ proposalUuid: "<proposal-uuid>" })
+   chorus_get_comments({ targetType: "proposal", targetUuid: "<proposal-uuid>" })
+   ```
+
+2. **Revise the drafts** based on feedback:
+   ```
+   chorus_update_task_draft({ proposalUuid: "<proposal-uuid>", draftUuid: "<draft-uuid>", ... })
+   chorus_update_document_draft({ proposalUuid: "<proposal-uuid>", draftUuid: "<draft-uuid>", ... })
+   ```
+
+3. **Validate and resubmit:**
+   ```
+   chorus_validate_proposal({ proposalUuid: "<proposal-uuid>" })
+   chorus_submit_proposal({ proposalUuid: "<proposal-uuid>" })
+   ```
+
+### Step 7: Post-Approval (SSE-Driven)
+
+When the `proposal_approved` SSE event fires:
+- Document drafts have become real Documents
+- Task drafts have become real Tasks (status: `open`, ready for developers)
+
+You can now assign tasks to developer agents:
+
+```
+chorus_pm_assign_task({ taskUuid: "<task-uuid>", agentUuid: "<developer-agent-uuid>" })
+```
+
+- Task must be `open` or `assigned`
+- Target agent must have `developer` or `developer_agent` role
+- Use `chorus_search_mentionables` to find the agent UUID
+
+### Step 8: Manage Post-Approval Dependencies (Optional)
+
+After tasks are created, you can manage dependencies on existing tasks:
+
+```
+chorus_update_task({
+  taskUuid: "<task-uuid>",
+  addDependsOn: ["<other-task-uuid>"],
+  removeDependsOn: ["<old-dependency-uuid>"]
+})
+```
+
+Or batch create additional tasks with intra-batch dependencies:
+
+```
+chorus_create_tasks({
+  projectUuid: "<project-uuid>",
+  tasks: [
+    { draftUuid: "draft-db", title: "Create database schema", priority: "high", storyPoints: 2 },
+    { draftUuid: "draft-api", title: "Implement API endpoints", priority: "high", storyPoints: 4, dependsOnDraftUuids: ["draft-db"] }
+  ]
+})
+```
+
+Dependencies are validated: same project, no self-dependency, no cycles (DFS detection).
+
+---
+
+## Document Writing Guidelines
+
+### PRD Structure
+```markdown
+# PRD: <Feature Name>
+
+## Background
+Why this feature is needed.
+
+## Requirements
+### Functional Requirements
+- FR-1: ...
+
+### Non-Functional Requirements
+- NFR-1: ...
+
+## User Stories
+- As a <role>, I want <action>, so that <benefit>
+
+## Out of Scope
+What is NOT included.
+```
+
+### Tech Design Structure
+```markdown
+# Technical Design: <Feature Name>
+
+## Overview
+High-level approach.
+
+## Architecture
+System design, component interactions.
+
+## Data Model
+Schema changes, new tables.
+
+## API Design
+New/modified endpoints.
+
+## Implementation Plan
+Step-by-step implementation order.
+
+## Risks & Mitigations
+Potential issues and how to address them.
+```
+
+### Task Writing Guidelines
+
+Good tasks are:
+- **Atomic** — One clear deliverable per task
+- **Testable** — Clear acceptance criteria with `acceptanceCriteriaItems`
+- **Sized** — 1-8 story points (hours of agent work)
+- **Ordered** — Use `dependsOnDraftUuids` to express execution order in the DAG
+- **Descriptive** — Include enough context for a developer agent to start without questions
+
+---
+
+## Tips
+
+- Keep PRD focused on *what* and *why*; tech design focused on *how*
+- Break large features into multiple smaller tasks rather than one monolithic task
+- Add `storyPoints` to help prioritize and estimate effort
+- Use `acceptanceCriteriaItems` with `required: true` for clear verification criteria
+- Always set up the task dependency DAG — tasks without dependencies are assumed parallelizable
+- When combining multiple ideas, explain how they relate in the proposal description
+- SSE events mean you do not need to poll for approval/rejection — the plugin wakes you automatically
+
+---
+
+## Next
+
+- After submission, an Admin will review using `/review`
+- After approval, Developers claim tasks using `/develop`
+- For Idea elaboration, see `/idea`
+- For platform overview, see `/chorus`

package/skills/quick-dev/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: quick-dev
+description: Quick Task workflow — skip Idea→Proposal, create tasks directly, execute, and verify.
+metadata:
+  openclaw:
+    emoji: "⚡"
+---
+
+# Quick Dev Skill
+
+Skip the full AI-DLC pipeline (Idea → Elaboration → Proposal → Approval) and create tasks directly. Ideal for small, well-understood work. The goal is for agents to **autonomously record their development work and verify task completion** through structured acceptance criteria.
+
+---
+
+## Overview
+
+The standard AI-DLC flow ensures quality through structured planning, but adds overhead that slows down small tasks. Quick Dev provides a lightweight alternative:
+
+```
+[check admin role] → chorus_create_tasks → chorus_claim_task → in_progress → report → self-check AC → submit for verify → [self-verify if admin] → done
+```
+
+**Use Quick Dev when:**
+- Bug fixes with clear reproduction steps
+- Small features (< 2 story points)
+- Post-delivery patches and gap-filling after a proposal's tasks are done
+- Prototype or exploratory tasks
+- Urgent hotfixes that can't wait for proposal review
+
+**Do NOT use Quick Dev when:**
+- The feature needs a PRD or tech design document
+- Multiple interdependent tasks require upfront planning
+- Stakeholder elaboration is needed to clarify requirements
+- The work impacts architecture or shared components significantly
+
+For complex work, use `/idea` + `/proposal` instead.
+
+---
+
+## Pre-Flight: Admin Self-Verify Check
+
+**Before creating tasks**, if you have the `admin_agent` role, ask the user:
+
+> "I have admin privileges. After development, should I verify the task myself, or leave it for another admin to verify?"
+
+This matters because admin agents can call `chorus_admin_verify_task` to close the loop autonomously. If the user approves self-verification, you can complete the entire create → develop → verify cycle without human intervention. Record the decision and apply it in Step 7.
+
+---
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `chorus_create_tasks` | Create task(s) — omit `proposalUuid` for standalone Quick Task, or pass it to attach to an existing proposal |
+| `chorus_update_task` | Edit task fields (title, description, priority, AC, dependencies) or change status |
+| `chorus_claim_task` | Claim a task (open → assigned) |
+| `chorus_report_work` | Report progress with optional status update |
+| `chorus_report_criteria_self_check` | Self-check acceptance criteria before submitting |
+| `chorus_submit_for_verify` | Submit for admin verification |
+| `chorus_admin_verify_task` | **(admin only)** Verify task — use when self-verification is approved |
+
+---
+
+## Workflow
+
+### Step 1: Create a Quick Task
+
+**Always include `acceptanceCriteriaItems`** — these are the foundation for self-checking in Step 6. Write specific, testable criteria that you can objectively verify after development. Vague AC like "works correctly" defeats the purpose; prefer "returns 200 on GET /api/foo with valid token".
+
+```
+chorus_create_tasks({
+  projectUuid: "<project-uuid>",
+  tasks: [{
+    title: "Fix login redirect loop on Safari",
+    description: "Safari loses session cookie after redirect...",
+    priority: "high",
+    storyPoints: 1,
+    acceptanceCriteriaItems: [
+      { description: "Login works on Safari 17+", required: true },
+      { description: "Existing Chrome/Firefox behavior unchanged", required: true }
+    ]
+  }]
+})
+```
+
+**`proposalUuid` is optional:**
+- **Omit** for standalone quick tasks (bug fixes, hotfixes, exploratory work)
+- **Pass** to attach the task to an existing proposal — useful for gap-filling, follow-up patches, or continuing work after a proposal's initial tasks are delivered
+
+### Step 2: Claim the Task
+
+```
+chorus_claim_task({ taskUuid: "<task-uuid>" })
+```
+
+### Step 3: Edit Details (if needed)
+
+Use `chorus_update_task` to refine the task after creation. **If you skipped AC in Step 1, add them now** — you will need them for self-check later. Also update AC when your understanding of the task changes during development.
+
+```
+chorus_update_task({
+  taskUuid: "<task-uuid>",
+  description: "Updated with more details...",
+  acceptanceCriteriaItems: [
+    { description: "Login works on Safari 17+", required: true },
+    { description: "Added CSRF token handling", required: true }
+  ],
+  addDependsOn: ["<other-task-uuid>"]
+})
+```
+
+### Step 4: Start Working
+
+```
+chorus_update_task({ taskUuid: "<task-uuid>", status: "in_progress" })
+```
+
+### Step 5: Report Progress
+
+```
+chorus_report_work({
+  taskUuid: "<task-uuid>",
+  report: "Fixed Safari cookie issue:\n- Root cause: SameSite=Strict incompatible with redirect\n- Changed to SameSite=Lax\n- Commit: abc1234"
+})
+```
+
+### Step 6: Self-Check Acceptance Criteria
+
+```
+chorus_report_criteria_self_check({
+  taskUuid: "<task-uuid>",
+  criteria: [
+    { uuid: "<ac-uuid-1>", devStatus: "passed", devEvidence: "Tested on Safari 17.2" },
+    { uuid: "<ac-uuid-2>", devStatus: "passed", devEvidence: "Chrome/Firefox regression tests pass" }
+  ]
+})
+```
+
+### Step 7: Submit for Verification (or Self-Verify)
+
+```
+chorus_submit_for_verify({
+  taskUuid: "<task-uuid>",
+  summary: "Fixed Safari login redirect loop. Changed SameSite cookie policy. All AC passed."
+})
+```
+
+**Admin self-verification:** If you have the `admin_agent` role and the user approved self-verification in the Pre-Flight check, you can verify the task yourself immediately after submitting:
+
+```
+chorus_admin_verify_task({ taskUuid: "<task-uuid>" })
+```
+
+This completes the full autonomous cycle: create → develop → verify → done.
+
+---
+
+## Tips
+
+- Keep Quick Tasks small — if you need more than 2-3 tasks, consider using `/proposal`
+- **Always write acceptance criteria at creation time** — they are your self-check contract. Specific, testable AC enables autonomous verification and makes the entire workflow self-contained
+- Use `chorus_update_task` to refine tasks (including AC) after creation rather than deleting and recreating
+- Pass `proposalUuid` to attach follow-up or gap-filling tasks to an existing proposal — this keeps related work grouped in the same project context and DAG
+- Quick Tasks show up in the same project task list and DAG as proposal-based tasks
+- Admin agents can run the full lifecycle autonomously (create → develop → self-verify) — but always confirm with the user first
+
+---
+
+## Next
+
+- For full task lifecycle details, see `/develop`
+- For admin verification, see `/review`
+- For the standard planning flow, see `/idea` and `/proposal`
+- For platform overview, see `/chorus`