chore: consolidate new foundation and archive v1 (#1495)
This commit is contained in:
@@ -0,0 +1,50 @@
|
||||
# Skill: glpi-create — Open a New GLPI Ticket
|
||||
|
||||
> Create a new GLPI helpdesk ticket. Mutates GLPI — confirm the details before running.
|
||||
|
||||
## When to use
|
||||
|
||||
- Logging a new incident or request that should live in the helpdesk queue.
|
||||
|
||||
## Required information
|
||||
|
||||
- **title** — short subject line.
|
||||
- **content** — description of the issue / request.
|
||||
|
||||
## Optional
|
||||
|
||||
- **priority** — `1`=VeryLow, `2`=Low, `3`=Medium (default), `4`=High, `5`=VeryHigh, `6`=Major.
|
||||
- **type** — `1`=Incident (default), `2`=Request.
|
||||
|
||||
## Command
|
||||
|
||||
Wraps the existing tooling:
|
||||
|
||||
```bash
|
||||
~/.config/mosaic/tools/glpi/ticket-create.sh \
|
||||
-t "<title>" \
|
||||
-c "<content>" \
|
||||
[-p <priority>] \
|
||||
[-y <type>] \
|
||||
[-f json]
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
~/.config/mosaic/tools/glpi/ticket-create.sh \
|
||||
-t "Paint-area camera install" \
|
||||
-c "Ordered 2 cameras for Paint and stock; schedule mounting + NVR config." \
|
||||
-p 3 -y 2
|
||||
```
|
||||
|
||||
## After creating
|
||||
|
||||
- Note the returned **ticket ID** — you'll need it for **[[glpi-followup]]** and
|
||||
**[[glpi-solve]]**.
|
||||
- If it should also be tracked as brain work, add a matching task (see the `add-task` skill).
|
||||
|
||||
## Guardrails
|
||||
|
||||
- Confirm title/content/priority with the user before creating — a ticket is outward-facing.
|
||||
- Never echo GLPI tokens.
|
||||
@@ -0,0 +1,56 @@
|
||||
# Skill: glpi-followup — Add a Followup to a GLPI Ticket
|
||||
|
||||
> Post a followup (comment / progress note / resolution writeup) to a GLPI ticket.
|
||||
> This documents work but does **not** change the ticket status — to close a ticket
|
||||
> out, follow with **[[glpi-solve]]** to set status to Solved.
|
||||
|
||||
## When to use
|
||||
|
||||
- Recording progress, a decision, or a root-cause/resolution note on a ticket.
|
||||
- The documentation step that usually precedes closing a ticket out (`glpi-solve`).
|
||||
|
||||
## Critical quirk
|
||||
|
||||
Use the **top-level `/ITILFollowup` endpoint**, NOT `/Ticket/<id>/ITILFollowup`. The
|
||||
sub-resource path returns permission errors even with a Super-Admin profile.
|
||||
|
||||
## Procedure
|
||||
|
||||
### 1. Session + creds
|
||||
|
||||
```bash
|
||||
SESSION=$(~/.config/mosaic/tools/glpi/session-init.sh -q)
|
||||
source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials glpi
|
||||
```
|
||||
|
||||
### 2. Post the followup
|
||||
|
||||
```bash
|
||||
TICKET_ID=<id>
|
||||
CONTENT="<the followup text>"
|
||||
curl -sk -X POST "${GLPI_URL}/ITILFollowup" \
|
||||
-H "App-Token: $GLPI_APP_TOKEN" \
|
||||
-H "Session-Token: $SESSION" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$(jq -n --argjson id "$TICKET_ID" --arg c "$CONTENT" \
|
||||
'{input:{itemtype:"Ticket", items_id:$id, content:$c}}')"
|
||||
```
|
||||
|
||||
Expect HTTP 201. Building the payload with `jq` keeps quotes/newlines in the content safe.
|
||||
|
||||
### 3. Long or multi-paragraph content
|
||||
|
||||
Write the note to a file first, then read it into the payload:
|
||||
|
||||
```bash
|
||||
curl -sk -X POST "${GLPI_URL}/ITILFollowup" \
|
||||
-H "App-Token: $GLPI_APP_TOKEN" -H "Session-Token: $SESSION" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$(jq -n --argjson id "$TICKET_ID" --rawfile c /path/to/note.md \
|
||||
'{input:{itemtype:"Ticket", items_id:$id, content:$c}}')"
|
||||
```
|
||||
|
||||
## Guardrails
|
||||
|
||||
- Never echo the GLPI app/user/session tokens.
|
||||
- A followup alone leaves the ticket open. If the work is done, run **[[glpi-solve]]** next.
|
||||
@@ -0,0 +1,57 @@
|
||||
# Skill: glpi-list — Query GLPI Tickets
|
||||
|
||||
> Quick lookups of GLPI helpdesk tickets by status or recency. Read-only.
|
||||
|
||||
## When to use
|
||||
|
||||
- "What tickets are open / pending?" · "Show recent tickets" · finding a ticket ID
|
||||
before running **[[glpi-followup]]** or **[[glpi-solve]]**.
|
||||
|
||||
## Command
|
||||
|
||||
Wraps the existing tooling:
|
||||
|
||||
```bash
|
||||
GLPI=~/.config/mosaic/tools/glpi
|
||||
|
||||
# Most recent tickets (default 50, newest first)
|
||||
"$GLPI/ticket-list.sh"
|
||||
|
||||
# Filter by status: new | processing | pending | solved | closed
|
||||
"$GLPI/ticket-list.sh" -s pending
|
||||
|
||||
# JSON output (for parsing / piping to jq) and a custom limit
|
||||
"$GLPI/ticket-list.sh" -s processing -f json -l 20
|
||||
```
|
||||
|
||||
Status IDs: 1 New · 2/3 Processing · 4 Pending · 5 Solved · 6 Closed.
|
||||
|
||||
## Details lookup for one ticket
|
||||
|
||||
When you have an ID and want the full record:
|
||||
|
||||
```bash
|
||||
SESSION=$(~/.config/mosaic/tools/glpi/session-init.sh -q)
|
||||
source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials glpi
|
||||
curl -sk "${GLPI_URL}/Ticket/<id>?expand_dropdowns=true" \
|
||||
-H "App-Token: $GLPI_APP_TOKEN" -H "Session-Token: $SESSION" \
|
||||
| jq '{id, name, status, date, date_mod}'
|
||||
|
||||
# Followups on a ticket
|
||||
curl -sk "${GLPI_URL}/Ticket/<id>/ITILFollowup" \
|
||||
-H "App-Token: $GLPI_APP_TOKEN" -H "Session-Token: $SESSION" \
|
||||
| jq '.[] | {date, content}'
|
||||
```
|
||||
|
||||
(Reading followups via the sub-resource is fine — only _creating_ them requires the
|
||||
top-level `/ITILFollowup` endpoint. See **[[glpi-followup]]**.)
|
||||
|
||||
## Present to user
|
||||
|
||||
Group by status, one line per ticket: `#<id> · <title> · <status> · <last-modified>`.
|
||||
Use neutral phrasing — no "OVERDUE"/"URGENT".
|
||||
|
||||
## Guardrails
|
||||
|
||||
- Read-only. Never echo GLPI tokens.
|
||||
- To sync tickets into brain data instead, use `python tools/sync_glpi.py` (not this skill).
|
||||
@@ -0,0 +1,96 @@
|
||||
# Skill: glpi-solve — Close Out a GLPI Ticket
|
||||
|
||||
> Properly close out a completed GLPI helpdesk ticket. Completing the work is not
|
||||
> enough — the ticket **status must be set to "Solved"**, which is what triggers
|
||||
> GLPI's config-driven auto-close. Posting a resolution followup documents the work
|
||||
> but does **not** change status, so a ticket left at Solved-less status stays open.
|
||||
|
||||
## When to use
|
||||
|
||||
- Any time work on a GLPI ticket is finished and it should be closed out.
|
||||
- After posting a root-cause / resolution writeup as an `/ITILFollowup`.
|
||||
- During a cleanup sweep of tickets that are done in reality but still open in GLPI.
|
||||
|
||||
## The rule (from an operator, 2026-07-20)
|
||||
|
||||
**"Solved" is the correct terminal state to set — not "Closed."** GLPI is configured
|
||||
to auto-close Solved tickets after its delay. If you only post a followup and never set
|
||||
status, the ticket sits open (this bit us on a real incident where resolution followups
|
||||
were posted but status was never advanced, leaving tickets open, which the operator had
|
||||
to mark Solved by hand).
|
||||
|
||||
Close-out = **followup (optional but preferred) + set status to Solved.**
|
||||
|
||||
## GLPI status IDs
|
||||
|
||||
| ID | Status | |
|
||||
| ----- | --------------------- | -------------------------------------------- |
|
||||
| 1 | New | |
|
||||
| 2 | Processing (assigned) | |
|
||||
| 3 | Processing (planned) | |
|
||||
| 4 | Pending / Waiting | |
|
||||
| **5** | **Solved** | ← set this on close-out |
|
||||
| 6 | Closed | ← happens automatically; do not set manually |
|
||||
|
||||
## Procedure
|
||||
|
||||
### 1. Get a session token
|
||||
|
||||
```bash
|
||||
SESSION=$(~/.config/mosaic/tools/glpi/session-init.sh -q)
|
||||
source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials glpi
|
||||
```
|
||||
|
||||
### 2. (Preferred) Post the resolution followup
|
||||
|
||||
Use the **top-level `/ITILFollowup` endpoint** — the `/Ticket/<id>/ITILFollowup`
|
||||
sub-resource returns permission errors even as Super-Admin (known GLPI quirk).
|
||||
|
||||
```bash
|
||||
TICKET_ID=<id>
|
||||
curl -sk -X POST "${GLPI_URL}/ITILFollowup" \
|
||||
-H "App-Token: $GLPI_APP_TOKEN" \
|
||||
-H "Session-Token: $SESSION" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{\"input\":{\"itemtype\":\"Ticket\",\"items_id\":${TICKET_ID},\"content\":\"<resolution summary>\"}}"
|
||||
```
|
||||
|
||||
### 3. Set status to Solved (the step that actually closes it out)
|
||||
|
||||
```bash
|
||||
curl -sk -X PUT "${GLPI_URL}/Ticket/${TICKET_ID}" \
|
||||
-H "App-Token: $GLPI_APP_TOKEN" \
|
||||
-H "Session-Token: $SESSION" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{\"input\":{\"id\":${TICKET_ID},\"status\":5}}"
|
||||
```
|
||||
|
||||
Expect HTTP 200/201. GLPI will auto-close it later per its config — leave status at 5.
|
||||
|
||||
### 4. Verify
|
||||
|
||||
```bash
|
||||
curl -sk "${GLPI_URL}/Ticket/${TICKET_ID}?expand_dropdowns=true" \
|
||||
-H "App-Token: $GLPI_APP_TOKEN" -H "Session-Token: $SESSION" \
|
||||
| jq '{id, name, status}'
|
||||
```
|
||||
|
||||
`status` should read `Solved` (or `5`).
|
||||
|
||||
## Optional: sweep for done-but-open tickets
|
||||
|
||||
List tickets still open (New/Processing/Pending) to spot ones whose work is actually
|
||||
finished but were never marked Solved:
|
||||
|
||||
```bash
|
||||
~/.config/mosaic/tools/glpi/ticket-list.sh -s processing -f table
|
||||
~/.config/mosaic/tools/glpi/ticket-list.sh -s pending -f table
|
||||
```
|
||||
|
||||
Review each; for any that are genuinely resolved, run steps 2–3.
|
||||
|
||||
## Guardrails
|
||||
|
||||
- Read-only until you intend to close — confirm the ticket is actually done first.
|
||||
- Never echo the GLPI app/user/session tokens.
|
||||
- Set **Solved (5)**, never Closed (6) — auto-close owns that transition.
|
||||
@@ -0,0 +1,62 @@
|
||||
# Skill: glpi-sweep — Find Done-But-Open Tickets
|
||||
|
||||
> Read-only sweep for tickets that are finished in reality but still sitting open in
|
||||
> GLPI (never moved to Solved). Surfaces the exact miss an operator caught on 2026-07-20
|
||||
> (a real incident where an affected ticket had resolution followups posted but was left
|
||||
> open). For each one that's genuinely done, close it out with **[[glpi-solve]]**.
|
||||
|
||||
## When to use
|
||||
|
||||
- Periodic hygiene pass (e.g. before a weekly update or month-end).
|
||||
- After a burst of ticket work, to catch any you resolved-in-followup but never Solved.
|
||||
|
||||
## Why this exists
|
||||
|
||||
Posting an `/ITILFollowup` documents work but does **not** change status. Tickets only
|
||||
auto-close once set to **Solved (status 5)**. Anything left at New/Processing/Pending
|
||||
stays open indefinitely. This sweep finds those.
|
||||
|
||||
## Procedure
|
||||
|
||||
### 1. List still-open tickets by status
|
||||
|
||||
```bash
|
||||
GLPI=~/.config/mosaic/tools/glpi
|
||||
"$GLPI/ticket-list.sh" -s new -f table
|
||||
"$GLPI/ticket-list.sh" -s processing -f table
|
||||
"$GLPI/ticket-list.sh" -s pending -f table
|
||||
```
|
||||
|
||||
(GLPI status IDs: 1 New · 2/3 Processing · 4 Pending · 5 Solved · 6 Closed.)
|
||||
|
||||
### 2. Triage
|
||||
|
||||
For each open ticket, judge whether the underlying work is actually finished — check
|
||||
its latest followups and cross-reference brain tasks / recent work. Read-only here;
|
||||
change nothing yet.
|
||||
|
||||
Reasonable "probably done" signals:
|
||||
|
||||
- A resolution/root-cause followup already posted, but status never advanced.
|
||||
- The related brain task is `done`, or the fix shipped and was confirmed.
|
||||
- Requester confirmed resolution but the ticket was never Solved.
|
||||
|
||||
### 3. Present the candidates
|
||||
|
||||
List them for review before touching anything — never bulk-solve blindly:
|
||||
|
||||
```
|
||||
Open tickets that look resolved:
|
||||
- #<id> "<title>" — <why it looks done> → glpi-solve?
|
||||
```
|
||||
|
||||
### 4. Close out the confirmed ones
|
||||
|
||||
For each ticket the user (or clear evidence) confirms is done, run **[[glpi-solve]]**
|
||||
(optionally **[[glpi-followup]]** first if a closing note is warranted).
|
||||
|
||||
## Guardrails
|
||||
|
||||
- Read-only until a ticket is confirmed done — do not auto-solve on a guess.
|
||||
- Never echo GLPI tokens.
|
||||
- Set **Solved (5)**, never Closed (6) — GLPI auto-close owns that transition.
|
||||
@@ -0,0 +1,155 @@
|
||||
---
|
||||
name: mosaic-board
|
||||
description: 'Run a Board of Directors review on a brief or proposal. CEO, CTO, CFO, and COO personas evaluate strategic, technical, financial, and operational viability. Use when you need a go/no-go decision, strategic review, or multi-perspective evaluation of a plan. Triggers on: board review, evaluate this brief, strategic review, go/no-go, board of directors.'
|
||||
---
|
||||
|
||||
# Mosaic Board of Directors
|
||||
|
||||
Run a multi-persona strategic review of a brief, proposal, or plan. Four executive personas independently evaluate, then a synthesis merges their verdicts into a single recommendation.
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
|
||||
- Evaluating a new feature, product, or architectural decision
|
||||
- Go/no-go decisions before committing resources
|
||||
- Strategic review of a PRD or project brief
|
||||
- Any time you want structured multi-perspective feedback
|
||||
|
||||
---
|
||||
|
||||
## The Board
|
||||
|
||||
| Role | Perspective | Key Question |
|
||||
| ------- | ------------------------------- | ------------------------------------------ |
|
||||
| **CEO** | Vision & mission alignment | "Does this serve the mission?" |
|
||||
| **CTO** | Technical feasibility & risk | "Can we actually build this?" |
|
||||
| **CFO** | Cost, ROI, budget impact | "What does this cost vs return?" |
|
||||
| **COO** | Operations, timeline, resources | "What's the timeline and resource impact?" |
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
### Step 1: Identify the Brief
|
||||
|
||||
The user provides a brief, PRD, proposal, or describes what they want reviewed. If no written document exists, help them articulate the key points:
|
||||
|
||||
- What is being proposed?
|
||||
- What problem does it solve?
|
||||
- What are the success criteria?
|
||||
- What are the known constraints?
|
||||
|
||||
### Step 2: Run Individual Reviews
|
||||
|
||||
For **each board member**, adopt their persona and evaluate the brief independently. Each review must output:
|
||||
|
||||
```json
|
||||
{
|
||||
"persona": "CEO|CTO|CFO|COO",
|
||||
"verdict": "approve|reject|conditional",
|
||||
"confidence": 0.0-1.0,
|
||||
"concerns": ["specific concern 1", "specific concern 2"],
|
||||
"recommendations": ["actionable recommendation 1"],
|
||||
"key_risks": ["identified risk 1"]
|
||||
}
|
||||
```
|
||||
|
||||
**Rules for each persona:**
|
||||
|
||||
- **CEO**: Focus on strategic alignment, market positioning, user value, mission fit. Ask "why should we do this?" not just "can we?"
|
||||
- **CTO**: Focus on architecture implications, technical debt, integration complexity, security surface. Be realistic about build effort.
|
||||
- **CFO**: Focus on cost (compute, human time, opportunity cost), ROI timeline, budget impact. Demand numbers or reasonable estimates.
|
||||
- **COO**: Focus on timeline, team capacity, operational overhead, maintenance burden, deployment complexity.
|
||||
|
||||
### Step 3: Synthesize
|
||||
|
||||
Merge all four reviews into a board synthesis:
|
||||
|
||||
- **Verdict**: `reject` if ANY member rejects. `conditional` if any member is conditional. `approve` only if all approve.
|
||||
- **Confidence**: Average of all member confidence scores.
|
||||
- **Concerns**: Deduplicated union of all concerns.
|
||||
- **Recommendations**: Deduplicated union of all recommendations.
|
||||
- **Key Risks**: Deduplicated union of all risks.
|
||||
|
||||
### Step 4: Present Results
|
||||
|
||||
Format the output as a readable Board Decision document:
|
||||
|
||||
```markdown
|
||||
# Board Decision: [Brief Title]
|
||||
|
||||
## Verdict: APPROVED / CONDITIONAL / REJECTED
|
||||
|
||||
**Confidence: X.XX**
|
||||
|
||||
## Individual Reviews
|
||||
|
||||
### CEO — [verdict]
|
||||
|
||||
- Concerns: ...
|
||||
- Recommendations: ...
|
||||
|
||||
### CTO — [verdict]
|
||||
|
||||
- Concerns: ...
|
||||
- Recommendations: ...
|
||||
|
||||
### CFO — [verdict]
|
||||
|
||||
- Concerns: ...
|
||||
- Recommendations: ...
|
||||
|
||||
### COO — [verdict]
|
||||
|
||||
- Concerns: ...
|
||||
- Recommendations: ...
|
||||
|
||||
## Synthesis
|
||||
|
||||
- Combined concerns: ...
|
||||
- Combined recommendations: ...
|
||||
- Key risks: ...
|
||||
|
||||
## Next Steps
|
||||
|
||||
[Based on verdict — what should happen next]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Standalone vs Full Pipeline
|
||||
|
||||
This skill works **standalone** — you don't need the full Mosaic Stack or Forge pipeline. Just invoke `/skill:mosaic-board` with any brief or proposal.
|
||||
|
||||
When used within the **Forge pipeline** (`@mosaicstack/forge`), the board stage is automated with parallel persona tasks and mechanical synthesis via `board-tasks.ts`.
|
||||
|
||||
---
|
||||
|
||||
## Board Persona Files
|
||||
|
||||
If detailed persona definitions exist at `~/.config/mosaic/forge/agents/board/`, load them for richer persona context. The personas work without these files — the role descriptions above are sufficient for standalone use.
|
||||
|
||||
---
|
||||
|
||||
## Classification Shortcut
|
||||
|
||||
Not every proposal needs a full board review:
|
||||
|
||||
- **Strategic** (new features, architecture, integrations, security): Full board review
|
||||
- **Technical** (refactors, bugfixes, UI tweaks): Skip board — go straight to implementation
|
||||
- **Hotfix** (urgent patches): Skip board and analysis — just fix it
|
||||
|
||||
If the user's request is clearly technical or a hotfix, suggest skipping the board review and proceeding directly.
|
||||
|
||||
---
|
||||
|
||||
## Save Results
|
||||
|
||||
Save the board decision to `docs/board-reviews/` or the project's `.forge/` directory:
|
||||
|
||||
```
|
||||
docs/board-reviews/YYYY-MM-DD-brief-name.md
|
||||
```
|
||||
|
||||
This creates an audit trail of strategic decisions.
|
||||
@@ -0,0 +1,227 @@
|
||||
---
|
||||
name: mosaic-forge
|
||||
description: 'Run the Mosaic Forge specialist pipeline — teams of specialized agents that plan, build, review, and deploy software through railed stages. Use when starting a project from a brief or PRD, running a multi-stage build pipeline, or orchestrating specialist agent teams. Triggers on: forge run, forge pipeline, specialist pipeline, run the forge, build this project, forge status.'
|
||||
---
|
||||
|
||||
# Mosaic Forge
|
||||
|
||||
Mosaic Forge is a railed specialist pipeline that replaces ad-hoc coding with structured stages: intake → board review → planning → coding → review → test → deploy. Each stage uses purpose-built agent personas.
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
|
||||
- Building a feature or project from a brief/PRD
|
||||
- Multi-stage work that needs architecture → implementation → review
|
||||
- Any task complex enough to benefit from structured planning before coding
|
||||
- When you want specialist perspectives (security, data, UX) before implementation
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### From an Existing Brief
|
||||
|
||||
```
|
||||
/skill:mosaic-forge run path/to/brief.md
|
||||
```
|
||||
|
||||
### From a Description
|
||||
|
||||
If no brief exists, the Forge intake stage will help create one:
|
||||
|
||||
```
|
||||
/skill:mosaic-forge run "Build a user notification system with email and in-app channels"
|
||||
```
|
||||
|
||||
### Check Status of a Run
|
||||
|
||||
```
|
||||
/skill:mosaic-forge status
|
||||
```
|
||||
|
||||
### Resume an Interrupted Run
|
||||
|
||||
```
|
||||
/skill:mosaic-forge resume
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Pipeline
|
||||
|
||||
```
|
||||
INTAKE → DISCOVERY → BOARD → BRIEF ANALYSIS → PLANNING 1 → PLANNING 2 → PLANNING 3 → CODING → REVIEW → REMEDIATE → TEST → DEPLOY
|
||||
```
|
||||
|
||||
### Stage Details
|
||||
|
||||
| # | Stage | Purpose | Who |
|
||||
| --- | ------------------ | ---------------------------- | ---------------------------------- |
|
||||
| 00 | **Intake** | Parse and validate the brief | Mechanical |
|
||||
| 00b | **Discovery** | Scan codebase for context | Codebase Scout |
|
||||
| 01 | **Board** | Strategic go/no-go | CEO, CTO, CFO, COO |
|
||||
| 01b | **Brief Analyzer** | Select specialist team | Sonnet agent |
|
||||
| 02 | **Planning 1** | Architecture decisions | Software Architect + generalists |
|
||||
| 03 | **Planning 2** | Implementation design | Language + domain specialists |
|
||||
| 04 | **Planning 3** | Task decomposition | Context Manager + Task Distributor |
|
||||
| 05 | **Coding** | Write the code | Codex/Claude workers |
|
||||
| 06 | **Review** | Evidence-driven review | Code reviewer + Security auditor |
|
||||
| 07 | **Remediate** | Fix review findings | Workers |
|
||||
| 08 | **Test** | Acceptance validation | QA Strategist |
|
||||
| 09 | **Deploy** | Ship it | Infrastructure Lead |
|
||||
|
||||
### Brief Classification (Skip Stages)
|
||||
|
||||
Not every brief needs every stage:
|
||||
|
||||
| Class | Skips | Use When |
|
||||
| ----------- | ----------------------- | ---------------------------------------- |
|
||||
| `strategic` | Nothing — full pipeline | New features, architecture, integrations |
|
||||
| `technical` | Board review | Refactors, bugfixes, UI tweaks |
|
||||
| `hotfix` | Board + Brief Analyzer | Urgent patches |
|
||||
|
||||
Classification is automatic (keyword analysis) but can be overridden:
|
||||
|
||||
- YAML frontmatter in the brief: `class: technical`
|
||||
- CLI flag: `--class hotfix`
|
||||
- Force board: `--force-board` on any class
|
||||
|
||||
---
|
||||
|
||||
## Standalone Mode
|
||||
|
||||
Forge works **without the full Mosaic Stack**. In standalone mode:
|
||||
|
||||
1. **You are the orchestrator** — advance through stages manually
|
||||
2. **Each stage is a conversation turn** — the agent adopts the stage's specialist persona(s)
|
||||
3. **Gates are checkpoints** — you decide when a stage passes
|
||||
|
||||
### Running Standalone
|
||||
|
||||
When invoked via `/skill:mosaic-forge`, run stages sequentially in the current session:
|
||||
|
||||
1. **Read the brief** — understand what's being built
|
||||
2. **Discovery** — scan the codebase (`find`, `grep`, read key files) to build context
|
||||
3. **Board Review** (if strategic) — run `/skill:mosaic-board` or do inline board evaluation
|
||||
4. **Planning 1** — propose architecture, debate trade-offs, produce an ADR
|
||||
5. **Planning 2** — detail implementation specs per component
|
||||
6. **Planning 3** — break into tasks with dependencies, estimates, acceptance criteria
|
||||
7. **Coding** — implement each task
|
||||
8. **Review** — self-review with evidence (grep for issues, check patterns)
|
||||
9. **Remediate** — fix anything found in review
|
||||
10. **Test** — run tests, verify acceptance criteria
|
||||
11. **Deploy** — if applicable
|
||||
|
||||
### Gate Checks Per Stage
|
||||
|
||||
After each stage, verify before advancing:
|
||||
|
||||
- **Board → Planning**: Brief approved, concerns addressed
|
||||
- **Planning 1 → 2**: ADR exists, covers all components
|
||||
- **Planning 2 → 3**: Impl specs per component, no conflicts
|
||||
- **Planning 3 → Coding**: Tasks have owners, criteria, estimates
|
||||
- **Coding → Review**: Compiles, lints, unit tests pass
|
||||
- **Review → Test**: All findings addressed
|
||||
- **Test → Deploy**: Acceptance criteria pass
|
||||
|
||||
---
|
||||
|
||||
## Full Pipeline Mode (Mosaic Stack)
|
||||
|
||||
When the full `@mosaicstack/forge` package is available, Forge uses MACP task execution:
|
||||
|
||||
```bash
|
||||
# Run from CLI
|
||||
# Fails closed with a typed FORGE_NO_EXECUTOR capability error when no real
|
||||
# executor is wired — pass --simulate to opt into explicit typed simulation
|
||||
# (every result carries status `simulated`, which satisfies nothing).
|
||||
mosaic forge run path/to/brief.md [--simulate]
|
||||
|
||||
# Resume interrupted run (same fail-closed rule as forge run)
|
||||
mosaic forge resume .forge/runs/20260401-143022/ [--simulate]
|
||||
|
||||
# Check status
|
||||
mosaic forge status .forge/runs/20260401-143022/
|
||||
```
|
||||
|
||||
Pipeline runs are tracked in `.forge/runs/{runId}/manifest.json`.
|
||||
|
||||
---
|
||||
|
||||
## Agent Roster
|
||||
|
||||
### Board (Static)
|
||||
|
||||
CEO, CTO, CFO, COO — see `/skill:mosaic-board`
|
||||
|
||||
### Generalists (Dynamic per brief)
|
||||
|
||||
- **Software Architect** — system design, boundaries, API contracts
|
||||
- **Security Architect** — threat modeling, auth, OWASP (always included)
|
||||
- **Infrastructure Lead** — deploy, networking, scaling
|
||||
- **Data Architect** — schema, migrations, query strategy
|
||||
- **QA Strategist** — test strategy, coverage
|
||||
- **UX Strategist** — user flows, accessibility
|
||||
|
||||
### Language Specialists (Dynamic)
|
||||
|
||||
TypeScript, JavaScript, Go, Rust, Solidity, Python, SQL
|
||||
|
||||
### Domain Specialists (Dynamic)
|
||||
|
||||
NestJS, React, Docker, CI/CD, Web Design, UX/UI, Kubernetes, AWS, Cloudflare, Proxmox, Portainer, DevOps, Ceph
|
||||
|
||||
---
|
||||
|
||||
## Debate Protocol
|
||||
|
||||
Planning stages use structured debate, not rubber-stamping:
|
||||
|
||||
1. **Independent positions** — each specialist states their position with reasoning
|
||||
2. **Responses** — specialists challenge each other's positions
|
||||
3. **Synthesis** — resolve disagreements, record dissents
|
||||
|
||||
Agents must argue, not agree. Premature consensus produces bad architecture.
|
||||
|
||||
---
|
||||
|
||||
## Artifacts
|
||||
|
||||
Each Forge run produces:
|
||||
|
||||
```
|
||||
.forge/runs/{runId}/
|
||||
├── manifest.json # Run state and stage statuses
|
||||
├── 00-intake/brief.md # Validated brief
|
||||
├── 00b-discovery/ # Codebase context
|
||||
├── 01-board/ # Board reviews + synthesis
|
||||
├── 02-planning-1/ # Architecture Decision Record
|
||||
├── 03-planning-2/ # Implementation specs
|
||||
├── 04-planning-3/ # Task breakdown
|
||||
├── 05-coding/ # Implementation output
|
||||
├── 06-review/ # Review findings
|
||||
├── 07-remediate/ # Fix log
|
||||
├── 08-test/ # Test results
|
||||
└── 09-deploy/ # Deploy log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project Configuration
|
||||
|
||||
Optional `.forge/config.yaml` in the project root:
|
||||
|
||||
```yaml
|
||||
board:
|
||||
skipMembers:
|
||||
- cfo # Skip CFO for internal tools
|
||||
additionalMembers:
|
||||
- legal # Add legal review for compliance projects
|
||||
|
||||
specialists:
|
||||
alwaysInclude:
|
||||
- security-architect
|
||||
```
|
||||
|
||||
Optional `.forge/personas/` for project-specific persona overrides (appended to base personas).
|
||||
@@ -0,0 +1,214 @@
|
||||
---
|
||||
name: mosaic-jarvis
|
||||
description: 'Jarvis Platform development context. Use when working on the jetrich/jarvis repository. Provides architecture knowledge, coding patterns, and component locations.'
|
||||
---
|
||||
|
||||
# Jarvis Platform Development
|
||||
|
||||
## Project Overview
|
||||
|
||||
Jarvis is a self-hosted AI assistant platform built with:
|
||||
|
||||
- **Backend:** FastAPI (Python 3.11+)
|
||||
- **Frontend:** Next.js 14+ (App Router)
|
||||
- **Database:** PostgreSQL with pgvector
|
||||
- **Plugins:** Modular LLM providers and integrations
|
||||
|
||||
Repository: `jetrich/jarvis`
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
jarvis/
|
||||
├── apps/
|
||||
│ ├── api/ # FastAPI backend
|
||||
│ │ └── src/
|
||||
│ │ ├── routes/ # API endpoints
|
||||
│ │ ├── services/ # Business logic
|
||||
│ │ ├── models/ # SQLAlchemy models
|
||||
│ │ └── core/ # Config, deps, security
|
||||
│ └── web/ # Next.js frontend
|
||||
│ └── src/
|
||||
│ ├── app/ # App router pages
|
||||
│ ├── components/ # React components
|
||||
│ └── lib/ # Utilities
|
||||
├── packages/
|
||||
│ └── plugins/ # jarvis_plugins package
|
||||
│ └── jarvis_plugins/
|
||||
│ ├── llm/ # LLM providers (ollama, claude, etc.)
|
||||
│ └── integrations/# External integrations
|
||||
├── docs/
|
||||
│ └── scratchpads/ # Agent working docs
|
||||
└── scripts/ # Utility scripts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Patterns
|
||||
|
||||
### LLM Provider Pattern
|
||||
|
||||
All LLM providers implement `BaseLLMProvider`:
|
||||
|
||||
```python
|
||||
# packages/plugins/jarvis_plugins/llm/base.py
|
||||
class BaseLLMProvider(ABC):
|
||||
@abstractmethod
|
||||
async def generate(self, prompt: str, **kwargs) -> str: ...
|
||||
|
||||
@abstractmethod
|
||||
async def stream(self, prompt: str, **kwargs) -> AsyncIterator[str]: ...
|
||||
```
|
||||
|
||||
### Integration Pattern
|
||||
|
||||
External integrations (GitHub, Calendar, etc.) follow:
|
||||
|
||||
```python
|
||||
# packages/plugins/jarvis_plugins/integrations/base.py
|
||||
class BaseIntegration(ABC):
|
||||
@abstractmethod
|
||||
async def authenticate(self, credentials: dict) -> bool: ...
|
||||
|
||||
@abstractmethod
|
||||
async def execute(self, action: str, params: dict) -> dict: ...
|
||||
```
|
||||
|
||||
### API Route Pattern
|
||||
|
||||
FastAPI routes use dependency injection:
|
||||
|
||||
```python
|
||||
@router.get("/items")
|
||||
async def list_items(
|
||||
db: Session = Depends(get_db),
|
||||
current_user: User = Depends(get_current_user),
|
||||
service: ItemService = Depends(get_item_service)
|
||||
):
|
||||
return await service.list(db, current_user.id)
|
||||
```
|
||||
|
||||
### Frontend Component Pattern
|
||||
|
||||
Use shadcn/ui + server components by default:
|
||||
|
||||
```tsx
|
||||
// Server component (default)
|
||||
export default async function DashboardPage() {
|
||||
const data = await fetchData();
|
||||
return <Dashboard data={data} />;
|
||||
}
|
||||
|
||||
// Client component (when needed)
|
||||
('use client');
|
||||
export function InteractiveWidget() {
|
||||
const [state, setState] = useState();
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Database
|
||||
|
||||
- **ORM:** SQLAlchemy 2.0+
|
||||
- **Migrations:** Alembic
|
||||
- **Vector Store:** pgvector extension
|
||||
|
||||
### Creating Migrations
|
||||
|
||||
```bash
|
||||
cd apps/api
|
||||
alembic revision --autogenerate -m "description"
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
### Backend
|
||||
|
||||
```bash
|
||||
cd apps/api
|
||||
pytest
|
||||
pytest --cov=src
|
||||
```
|
||||
|
||||
### Frontend
|
||||
|
||||
```bash
|
||||
cd apps/web
|
||||
npm test
|
||||
npm run test:e2e
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality Commands
|
||||
|
||||
```bash
|
||||
# Backend
|
||||
cd apps/api
|
||||
ruff check .
|
||||
ruff format .
|
||||
mypy src/
|
||||
|
||||
# Frontend
|
||||
cd apps/web
|
||||
npm run lint
|
||||
npm run typecheck
|
||||
npm run format
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Active Development Areas
|
||||
|
||||
| Issue | Feature | Priority |
|
||||
| ----- | ------------------------------------- | -------- |
|
||||
| #84 | Per-function LLM routing | High |
|
||||
| #85 | Embedded E2E autonomous delivery loop | High |
|
||||
| #86 | Thinking models (CoT UI) | Medium |
|
||||
| #87 | Local image generation | Medium |
|
||||
| #88 | Deep research mode | Medium |
|
||||
| #89 | Uncensored models + alignment | Medium |
|
||||
| #90 | OCR capabilities | Medium |
|
||||
| #91 | Authentik SSO | Medium |
|
||||
| #40 | Claude Max + Claude Code | High |
|
||||
|
||||
---
|
||||
|
||||
## Environment Setup
|
||||
|
||||
```bash
|
||||
# Backend
|
||||
cd apps/api
|
||||
cp .env.example .env
|
||||
pip install -e ".[dev]"
|
||||
|
||||
# Frontend
|
||||
cd apps/web
|
||||
cp .env.example .env.local
|
||||
npm install
|
||||
|
||||
# Database
|
||||
docker-compose up -d postgres
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Commit Convention
|
||||
|
||||
```
|
||||
<type>(#issue): Brief description
|
||||
|
||||
Detailed explanation if needed.
|
||||
|
||||
Fixes #123
|
||||
```
|
||||
|
||||
Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
name: mosaic-macp
|
||||
description: Manage MACP tasks — submit, check status, view history, and drain queues. Use when orchestrating coding tasks via the Mosaic Agent Coordination Protocol.
|
||||
---
|
||||
|
||||
# macp
|
||||
|
||||
MACP task management via the mosaic CLI.
|
||||
|
||||
## Setup
|
||||
|
||||
Ensure PATH includes mosaic bin:
|
||||
|
||||
```bash
|
||||
export PATH="$HOME/.config/mosaic/bin:$PATH"
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Purpose |
|
||||
| ----------------------------------------------------------------------------- | -------------------------------------------------------------- |
|
||||
| `mosaic macp status` | Show queue counts (pending/running/completed/failed/escalated) |
|
||||
| `mosaic macp submit --task-id ID --title "..." --type coding --command "..."` | Submit a task |
|
||||
| `mosaic macp history --task-id ID` | Show event history for a task |
|
||||
| `mosaic macp drain` | Run all pending tasks sequentially |
|
||||
| `mosaic macp watch --once` | Poll events once |
|
||||
|
||||
## Common Workflows
|
||||
|
||||
**Check what's in the queue:**
|
||||
|
||||
```bash
|
||||
export PATH="$HOME/.config/mosaic/bin:$PATH"
|
||||
mosaic macp status
|
||||
```
|
||||
|
||||
**Submit a coding task:**
|
||||
|
||||
```bash
|
||||
mosaic macp submit --task-id TASK-001 --title "Fix auth bug" --type coding --command "echo done"
|
||||
```
|
||||
|
||||
**View task history:**
|
||||
|
||||
```bash
|
||||
mosaic macp history --task-id TASK-001
|
||||
```
|
||||
@@ -0,0 +1,264 @@
|
||||
---
|
||||
name: mosaic-prd
|
||||
description: 'Generate a Product Requirements Document (PRD) for a new feature. Use when planning a feature, starting a new project, or when asked to create a PRD. Triggers on: create a prd, write prd for, plan this feature, requirements for, spec out.'
|
||||
---
|
||||
|
||||
# PRD Generator
|
||||
|
||||
Create detailed Product Requirements Documents that are clear, actionable, and suitable for implementation.
|
||||
|
||||
---
|
||||
|
||||
## The Job
|
||||
|
||||
1. Receive a feature description from the user
|
||||
2. Ask 3-5 essential clarifying questions (with lettered options)
|
||||
3. Generate a structured PRD based on answers
|
||||
4. Save to `tasks/prd-[feature-name].md`
|
||||
|
||||
**Important:** Do NOT start implementing. Just create the PRD.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Clarifying Questions
|
||||
|
||||
Ask only critical questions where the initial prompt is ambiguous. Focus on:
|
||||
|
||||
- **Problem/Goal:** What problem does this solve?
|
||||
- **Core Functionality:** What are the key actions?
|
||||
- **Scope/Boundaries:** What should it NOT do?
|
||||
- **Success Criteria:** How do we know it's done?
|
||||
|
||||
### Format Questions Like This:
|
||||
|
||||
```
|
||||
1. What is the primary goal of this feature?
|
||||
A. Improve user onboarding experience
|
||||
B. Increase user retention
|
||||
C. Reduce support burden
|
||||
D. Other: [please specify]
|
||||
|
||||
2. Who is the target user?
|
||||
A. New users only
|
||||
B. Existing users only
|
||||
C. All users
|
||||
D. Admin users only
|
||||
|
||||
3. What is the scope?
|
||||
A. Minimal viable version
|
||||
B. Full-featured implementation
|
||||
C. Just the backend/API
|
||||
D. Just the UI
|
||||
```
|
||||
|
||||
This lets users respond with "1A, 2C, 3B" for quick iteration.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: PRD Structure
|
||||
|
||||
Generate the PRD with these sections:
|
||||
|
||||
### 1. Introduction/Overview
|
||||
|
||||
Brief description of the feature and the problem it solves.
|
||||
|
||||
### 2. Goals
|
||||
|
||||
Specific, measurable objectives (bullet list).
|
||||
|
||||
### 3. User Stories
|
||||
|
||||
Each story needs:
|
||||
|
||||
- **Title:** Short descriptive name
|
||||
- **Description:** "As a [user], I want [feature] so that [benefit]"
|
||||
- **Acceptance Criteria:** Verifiable checklist of what "done" means
|
||||
|
||||
Each story should be small enough to implement in one focused session.
|
||||
|
||||
**Format:**
|
||||
|
||||
```markdown
|
||||
### US-001: [Title]
|
||||
|
||||
**Description:** As a [user], I want [feature] so that [benefit].
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] Specific verifiable criterion
|
||||
- [ ] Another criterion
|
||||
- [ ] Typecheck/lint passes
|
||||
- [ ] **[UI stories only]** Verify in browser using dev-browser skill
|
||||
```
|
||||
|
||||
**Important:**
|
||||
|
||||
- Acceptance criteria must be verifiable, not vague. "Works correctly" is bad. "Button shows confirmation dialog before deleting" is good.
|
||||
- **For any story with UI changes:** Always include "Verify in browser using dev-browser skill" as acceptance criteria. This ensures visual verification of frontend work.
|
||||
|
||||
### 4. Functional Requirements
|
||||
|
||||
Numbered list of specific functionalities:
|
||||
|
||||
- "FR-1: The system must allow users to..."
|
||||
- "FR-2: When a user clicks X, the system must..."
|
||||
|
||||
Be explicit and unambiguous.
|
||||
|
||||
### 5. Non-Goals (Out of Scope)
|
||||
|
||||
What this feature will NOT include. Critical for managing scope.
|
||||
|
||||
### 6. Design Considerations (Optional)
|
||||
|
||||
- UI/UX requirements
|
||||
- Link to mockups if available
|
||||
- Relevant existing components to reuse
|
||||
|
||||
### 7. Technical Considerations (Optional)
|
||||
|
||||
- Known constraints or dependencies
|
||||
- Integration points with existing systems
|
||||
- Performance requirements
|
||||
|
||||
### 8. Success Metrics
|
||||
|
||||
How will success be measured?
|
||||
|
||||
- "Reduce time to complete X by 50%"
|
||||
- "Increase conversion rate by 10%"
|
||||
|
||||
### 9. Open Questions
|
||||
|
||||
Remaining questions or areas needing clarification.
|
||||
|
||||
---
|
||||
|
||||
## Writing for Junior Developers
|
||||
|
||||
The PRD reader may be a junior developer or AI agent. Therefore:
|
||||
|
||||
- Be explicit and unambiguous
|
||||
- Avoid jargon or explain it
|
||||
- Provide enough detail to understand purpose and core logic
|
||||
- Number requirements for easy reference
|
||||
- Use concrete examples where helpful
|
||||
|
||||
---
|
||||
|
||||
## Output
|
||||
|
||||
- **Format:** Markdown (`.md`)
|
||||
- **Location:** `tasks/`
|
||||
- **Filename:** `prd-[feature-name].md` (kebab-case)
|
||||
|
||||
---
|
||||
|
||||
## Example PRD
|
||||
|
||||
```markdown
|
||||
# PRD: Task Priority System
|
||||
|
||||
## Introduction
|
||||
|
||||
Add priority levels to tasks so users can focus on what matters most. Tasks can be marked as high, medium, or low priority, with visual indicators and filtering to help users manage their workload effectively.
|
||||
|
||||
## Goals
|
||||
|
||||
- Allow assigning priority (high/medium/low) to any task
|
||||
- Provide clear visual differentiation between priority levels
|
||||
- Enable filtering and sorting by priority
|
||||
- Default new tasks to medium priority
|
||||
|
||||
## User Stories
|
||||
|
||||
### US-001: Add priority field to database
|
||||
|
||||
**Description:** As a developer, I need to store task priority so it persists across sessions.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] Add priority column to tasks table: 'high' | 'medium' | 'low' (default 'medium')
|
||||
- [ ] Generate and run migration successfully
|
||||
- [ ] Typecheck passes
|
||||
|
||||
### US-002: Display priority indicator on task cards
|
||||
|
||||
**Description:** As a user, I want to see task priority at a glance so I know what needs attention first.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] Each task card shows colored priority badge (red=high, yellow=medium, gray=low)
|
||||
- [ ] Priority visible without hovering or clicking
|
||||
- [ ] Typecheck passes
|
||||
- [ ] Verify in browser using dev-browser skill
|
||||
|
||||
### US-003: Add priority selector to task edit
|
||||
|
||||
**Description:** As a user, I want to change a task's priority when editing it.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] Priority dropdown in task edit modal
|
||||
- [ ] Shows current priority as selected
|
||||
- [ ] Saves immediately on selection change
|
||||
- [ ] Typecheck passes
|
||||
- [ ] Verify in browser using dev-browser skill
|
||||
|
||||
### US-004: Filter tasks by priority
|
||||
|
||||
**Description:** As a user, I want to filter the task list to see only high-priority items when I'm focused.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] Filter dropdown with options: All | High | Medium | Low
|
||||
- [ ] Filter persists in URL params
|
||||
- [ ] Empty state message when no tasks match filter
|
||||
- [ ] Typecheck passes
|
||||
- [ ] Verify in browser using dev-browser skill
|
||||
|
||||
## Functional Requirements
|
||||
|
||||
- FR-1: Add `priority` field to tasks table ('high' | 'medium' | 'low', default 'medium')
|
||||
- FR-2: Display colored priority badge on each task card
|
||||
- FR-3: Include priority selector in task edit modal
|
||||
- FR-4: Add priority filter dropdown to task list header
|
||||
- FR-5: Sort by priority within each status column (high to medium to low)
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- No priority-based notifications or reminders
|
||||
- No automatic priority assignment based on due date
|
||||
- No priority inheritance for subtasks
|
||||
|
||||
## Technical Considerations
|
||||
|
||||
- Reuse existing badge component with color variants
|
||||
- Filter state managed via URL search params
|
||||
- Priority stored in database, not computed
|
||||
|
||||
## Success Metrics
|
||||
|
||||
- Users can change priority in under 2 clicks
|
||||
- High-priority tasks immediately visible at top of lists
|
||||
- No regression in task list performance
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should priority affect task ordering within a column?
|
||||
- Should we add keyboard shortcuts for priority changes?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
|
||||
Before saving the PRD:
|
||||
|
||||
- [ ] Asked clarifying questions with lettered options
|
||||
- [ ] Incorporated user's answers
|
||||
- [ ] User stories are small and specific
|
||||
- [ ] Functional requirements are numbered and unambiguous
|
||||
- [ ] Non-goals section defines clear boundaries
|
||||
- [ ] Saved to `tasks/prd-[feature-name].md`
|
||||
@@ -0,0 +1,275 @@
|
||||
---
|
||||
name: mosaic-prdy
|
||||
description: 'Create, update, validate, and manage Product Requirements Documents (PRDs) using the Mosaic PRDy system. Use when planning features, writing requirements, validating PRDs against standards, or checking PRD status. Triggers on: create a prd, write prd, prdy init, prdy validate, plan this feature, requirements document, spec out.'
|
||||
---
|
||||
|
||||
# Mosaic PRDy
|
||||
|
||||
PRDy is Mosaic's PRD (Product Requirements Document) lifecycle manager. Create structured PRDs from templates, validate them against quality standards, and track their status through draft → review → approved → archived.
|
||||
|
||||
---
|
||||
|
||||
## Commands
|
||||
|
||||
### Initialize a New PRD
|
||||
|
||||
```
|
||||
/skill:mosaic-prdy init --name "Feature Name"
|
||||
```
|
||||
|
||||
Or describe what you want to build and PRDy will guide you through it:
|
||||
|
||||
```
|
||||
/skill:mosaic-prdy init "Build a notification system with email and in-app channels"
|
||||
```
|
||||
|
||||
### Update an Existing PRD
|
||||
|
||||
```
|
||||
/skill:mosaic-prdy update
|
||||
```
|
||||
|
||||
Scans the project for existing PRDs and offers to update sections.
|
||||
|
||||
### Validate a PRD
|
||||
|
||||
```
|
||||
/skill:mosaic-prdy validate
|
||||
```
|
||||
|
||||
Checks all PRDs against Mosaic quality standards:
|
||||
|
||||
- Required sections present
|
||||
- Acceptance criteria are specific and verifiable
|
||||
- Non-goals defined
|
||||
- Success metrics measurable
|
||||
|
||||
### Check Status
|
||||
|
||||
```
|
||||
/skill:mosaic-prdy status
|
||||
```
|
||||
|
||||
Lists all PRDs in the project with their current status.
|
||||
|
||||
---
|
||||
|
||||
## The Job
|
||||
|
||||
### Step 1: Clarifying Questions
|
||||
|
||||
Ask 3-5 essential questions with lettered options (user responds "1A, 2C, 3B"):
|
||||
|
||||
```
|
||||
1. What is the primary goal?
|
||||
A. Improve user experience
|
||||
B. Increase retention
|
||||
C. Reduce support burden
|
||||
D. Other: [specify]
|
||||
|
||||
2. Who is the target user?
|
||||
A. New users only
|
||||
B. All users
|
||||
C. Admin users
|
||||
D. Other: [specify]
|
||||
|
||||
3. What is the scope?
|
||||
A. Minimal viable version
|
||||
B. Full-featured
|
||||
C. Backend/API only
|
||||
D. UI only
|
||||
```
|
||||
|
||||
### Step 2: Generate PRD
|
||||
|
||||
Using the Mosaic PRD template with these required sections:
|
||||
|
||||
1. **Introduction/Overview** — problem statement and what this solves
|
||||
2. **Goals** — specific, measurable objectives
|
||||
3. **User Stories** — with acceptance criteria (see format below)
|
||||
4. **Functional Requirements** — numbered (FR-1, FR-2, ...)
|
||||
5. **Non-Functional Requirements** — security, performance, reliability, observability
|
||||
6. **Non-Goals (Out of Scope)** — explicit boundaries
|
||||
7. **Design Considerations** — UI/UX, mockups, reusable components
|
||||
8. **Technical Considerations** — constraints, dependencies, integrations
|
||||
9. **Success Metrics** — measurable outcomes
|
||||
10. **Open Questions** — unresolved items
|
||||
|
||||
### Step 3: Save
|
||||
|
||||
Save to `tasks/prd-[feature-name].md` (kebab-case).
|
||||
|
||||
---
|
||||
|
||||
## User Story Format
|
||||
|
||||
Each story must be small enough to implement in one focused session:
|
||||
|
||||
```markdown
|
||||
### US-001: [Title]
|
||||
|
||||
**Description:** As a [user], I want [feature] so that [benefit].
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] Specific verifiable criterion (not "works correctly")
|
||||
- [ ] Another criterion with measurable outcome
|
||||
- [ ] Typecheck/lint passes
|
||||
- [ ] **[UI stories]** Verify in browser using dev-browser skill
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
|
||||
- Acceptance criteria must be verifiable, not vague
|
||||
- "Button shows confirmation dialog before deleting" ✅
|
||||
- "Works correctly" ❌
|
||||
- UI stories always include browser verification
|
||||
- Each story gets a unique ID (US-001, US-002, ...)
|
||||
|
||||
---
|
||||
|
||||
## PRD Lifecycle
|
||||
|
||||
```
|
||||
draft → review → approved → archived
|
||||
```
|
||||
|
||||
| Status | Meaning |
|
||||
| ---------- | ---------------------------------------------- |
|
||||
| `draft` | Work in progress, not ready for implementation |
|
||||
| `review` | Ready for stakeholder review |
|
||||
| `approved` | Approved for implementation — the contract |
|
||||
| `archived` | Completed or abandoned |
|
||||
|
||||
**Key rule:** Implementation that diverges from an approved PRD without updating the PRD first is a blocker. Change control: update PRD → update plan → then implement.
|
||||
|
||||
---
|
||||
|
||||
## Templates
|
||||
|
||||
PRDy ships with built-in templates:
|
||||
|
||||
| Template | Use When |
|
||||
| ---------------- | ----------------------------------- |
|
||||
| `feature` | New feature or capability (default) |
|
||||
| `integration` | Third-party integration or API |
|
||||
| `infrastructure` | DevOps, deployment, scaling |
|
||||
| `refactor` | Technical debt, architecture change |
|
||||
|
||||
Specify a template:
|
||||
|
||||
```
|
||||
/skill:mosaic-prdy init --name "Auth Integration" --template integration
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Rules
|
||||
|
||||
`/skill:mosaic-prdy validate` checks:
|
||||
|
||||
- [ ] Has introduction/overview
|
||||
- [ ] Has at least one goal
|
||||
- [ ] Has at least one user story with acceptance criteria
|
||||
- [ ] Functional requirements are numbered
|
||||
- [ ] Non-goals section exists and is non-empty
|
||||
- [ ] Acceptance criteria are specific (flags vague terms: "works correctly", "handles properly", "is fast")
|
||||
- [ ] Success metrics are measurable
|
||||
- [ ] No TODO/TBD markers in approved PRDs
|
||||
|
||||
---
|
||||
|
||||
## Integration with Forge
|
||||
|
||||
When used with Mosaic Forge (`/skill:mosaic-forge`):
|
||||
|
||||
1. PRDy creates the PRD (this skill)
|
||||
2. Forge decomposes the PRD into briefs
|
||||
3. Board reviews each brief
|
||||
4. Pipeline builds each brief through specialist stages
|
||||
|
||||
PRDy is the **input** to the Forge pipeline. A well-written PRD means less rework in planning stages.
|
||||
|
||||
---
|
||||
|
||||
## Standalone CLI
|
||||
|
||||
If the `mosaic` CLI is available:
|
||||
|
||||
```bash
|
||||
mosaic prdy init --name "Feature Name"
|
||||
mosaic prdy update
|
||||
mosaic prdy validate
|
||||
mosaic prdy status
|
||||
|
||||
# With runtime selection
|
||||
mosaic prdy --pi init --name "Feature Name"
|
||||
mosaic prdy --claude init --name "Feature Name"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Writing for Junior Developers
|
||||
|
||||
PRDs may be read by junior developers or AI agents. Therefore:
|
||||
|
||||
- Be explicit and unambiguous
|
||||
- Avoid jargon or explain it
|
||||
- Provide enough detail to understand purpose and core logic
|
||||
- Number requirements for easy reference
|
||||
- Use concrete examples where helpful
|
||||
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
```markdown
|
||||
# PRD: Task Priority System
|
||||
|
||||
## Introduction
|
||||
|
||||
Add priority levels to tasks so users can focus on what matters most.
|
||||
|
||||
## Goals
|
||||
|
||||
- Allow assigning priority (high/medium/low) to any task
|
||||
- Provide clear visual differentiation between priority levels
|
||||
- Enable filtering and sorting by priority
|
||||
|
||||
## User Stories
|
||||
|
||||
### US-001: Add priority field to database
|
||||
|
||||
**Description:** As a developer, I need to store task priority persistently.
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] Add priority column: 'high' | 'medium' | 'low' (default 'medium')
|
||||
- [ ] Migration runs successfully
|
||||
- [ ] Typecheck passes
|
||||
|
||||
### US-002: Display priority indicator
|
||||
|
||||
**Description:** As a user, I want to see task priority at a glance.
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] Colored badge: red=high, yellow=medium, gray=low
|
||||
- [ ] Priority visible without hovering
|
||||
- [ ] Verify in browser
|
||||
|
||||
## Functional Requirements
|
||||
|
||||
- FR-1: Add `priority` field ('high'|'medium'|'low', default 'medium')
|
||||
- FR-2: Display colored priority badge on each task card
|
||||
- FR-3: Priority filter dropdown in task list header
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- No priority-based notifications
|
||||
- No automatic priority assignment
|
||||
- No priority inheritance for subtasks
|
||||
|
||||
## Success Metrics
|
||||
|
||||
- Users can change priority in under 2 clicks
|
||||
- High-priority tasks visible at top of lists
|
||||
```
|
||||
@@ -0,0 +1,309 @@
|
||||
---
|
||||
name: mosaic-setup-cicd
|
||||
description: 'Configure CI/CD Docker build, push, and package linking for a project. Use when adding Docker builds to a Woodpecker pipeline, setting up Gitea container registry, or implementing CI/CD for deployment. Triggers on: setup cicd, add docker builds, configure pipeline, add ci/cd, setup ci.'
|
||||
---
|
||||
|
||||
# CI/CD Pipeline Setup
|
||||
|
||||
Configure Docker build, registry push, and package linking for a Woodpecker CI pipeline using Kaniko and Gitea's container registry.
|
||||
|
||||
**Before starting:** Read `~/.config/mosaic/guides/CI-CD-PIPELINES.md` for deep background on the patterns used here.
|
||||
|
||||
**Reference implementation:** `~/src/mosaic-stack/.woodpecker.yml`
|
||||
|
||||
---
|
||||
|
||||
## The Job
|
||||
|
||||
1. Scan the current project for services, Dockerfiles, and registry info
|
||||
2. Ask clarifying questions about what to build and how to name images
|
||||
3. Generate Woodpecker YAML for Docker build/push/link steps
|
||||
4. Provide secrets configuration commands
|
||||
5. Output a verification checklist
|
||||
|
||||
**Important:** This skill generates YAML to _append_ to an existing `.woodpecker.yml`, not replace it. The project should already have quality gate steps (lint, test, typecheck, build).
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Project Scan
|
||||
|
||||
Run these scans and present results to the user:
|
||||
|
||||
### 1a. Detect registry info from git remote
|
||||
|
||||
```bash
|
||||
# Extract Gitea host and org/repo from remote
|
||||
REMOTE_URL=$(git remote get-url origin 2>/dev/null)
|
||||
# Parse: https://git.example.com/org/repo.git -> host=git.example.com, org=org, repo=repo
|
||||
```
|
||||
|
||||
Present:
|
||||
|
||||
- **Registry host:** (extracted from remote)
|
||||
- **Organization:** (extracted from remote)
|
||||
- **Repository:** (extracted from remote)
|
||||
|
||||
### 1b. Find all Dockerfiles
|
||||
|
||||
```bash
|
||||
find . -name "Dockerfile" -o -name "Dockerfile.*" | grep -v node_modules | grep -v .git | sort
|
||||
```
|
||||
|
||||
For each Dockerfile found, note:
|
||||
|
||||
- Path relative to project root
|
||||
- Whether it's a dev variant (`Dockerfile.dev`) or production
|
||||
- The service name (inferred from parent directory)
|
||||
|
||||
### 1c. Detect existing pipeline
|
||||
|
||||
```bash
|
||||
cat .woodpecker.yml 2>/dev/null || cat .woodpecker/*.yml 2>/dev/null
|
||||
```
|
||||
|
||||
Check:
|
||||
|
||||
- Does a `build` step exist? (Docker builds will depend on it)
|
||||
- Are there already Docker build steps? (avoid duplicating)
|
||||
- What's the existing dependency chain?
|
||||
|
||||
### 1d. Find publishable npm packages (if applicable)
|
||||
|
||||
```bash
|
||||
# Find package.json files without "private": true
|
||||
find . -name "package.json" -not -path "*/node_modules/*" -exec grep -L '"private": true' {} \;
|
||||
```
|
||||
|
||||
### 1e. Present scan results
|
||||
|
||||
Show the user a summary table:
|
||||
|
||||
```
|
||||
=== CI/CD Scan Results ===
|
||||
Registry: git.example.com
|
||||
Organization: org-name
|
||||
Repository: repo-name
|
||||
|
||||
Dockerfiles Found:
|
||||
1. src/backend-api/Dockerfile → backend-api
|
||||
2. src/web-portal/Dockerfile → web-portal
|
||||
3. src/ingest-api/Dockerfile → ingest-api
|
||||
4. src/backend-api/Dockerfile.dev → (dev variant, skip)
|
||||
|
||||
Existing Pipeline: .woodpecker.yml
|
||||
- Has build step: yes (build-all)
|
||||
- Has Docker steps: no
|
||||
|
||||
Publishable npm Packages:
|
||||
- @scope/schemas (src/schemas)
|
||||
- @scope/design-system (src/design-system)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Clarifying Questions
|
||||
|
||||
Ask these questions with lettered options (user can respond "1A, 2B, 3C"):
|
||||
|
||||
```
|
||||
1. Which Dockerfiles should be built in CI?
|
||||
(Select all that apply — list found Dockerfiles with letters)
|
||||
A. src/backend-api/Dockerfile (backend-api)
|
||||
B. src/web-portal/Dockerfile (web-portal)
|
||||
C. src/ingest-api/Dockerfile (ingest-api)
|
||||
D. All of the above
|
||||
E. Other: [specify]
|
||||
|
||||
2. Image naming convention?
|
||||
A. {org}/{service} (e.g., usc/uconnect-backend-api) — Recommended
|
||||
B. {org}/{repo}-{service} (e.g., usc/uconnect-backend-api)
|
||||
C. Custom: [specify]
|
||||
|
||||
3. Do any services need build arguments?
|
||||
A. No build args needed
|
||||
B. Yes: [specify service:KEY=VALUE, e.g., web-portal:NEXT_PUBLIC_API_URL=https://api.example.com]
|
||||
|
||||
4. Which branches should trigger Docker builds?
|
||||
A. main and develop (Recommended)
|
||||
B. main only
|
||||
C. Custom: [specify]
|
||||
|
||||
5. Should npm packages be published? (only if publishable packages found)
|
||||
A. Yes, to Gitea npm registry
|
||||
B. Yes, to custom registry: [specify URL]
|
||||
C. No, skip npm publishing
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Generate Pipeline YAML
|
||||
|
||||
### 3a. Add kaniko_setup anchor
|
||||
|
||||
If the project's `.woodpecker.yml` doesn't already have a `kaniko_setup` anchor in its `variables:` section, add it:
|
||||
|
||||
```bash
|
||||
~/.config/mosaic/tools/cicd/generate-docker-steps.sh --kaniko-setup-only --registry REGISTRY_HOST
|
||||
```
|
||||
|
||||
This outputs:
|
||||
|
||||
```yaml
|
||||
# Kaniko base command setup
|
||||
- &kaniko_setup |
|
||||
mkdir -p /kaniko/.docker
|
||||
echo "{\"auths\":{\"REGISTRY\":{\"username\":\"$GITEA_USER\",\"password\":\"$GITEA_TOKEN\"}}}" > /kaniko/.docker/config.json
|
||||
```
|
||||
|
||||
Add this to the existing `variables:` block at the top of `.woodpecker.yml`.
|
||||
|
||||
### 3b. Generate Docker build/push/link steps
|
||||
|
||||
Use the generator script with the user's answers:
|
||||
|
||||
```bash
|
||||
~/.config/mosaic/tools/cicd/generate-docker-steps.sh \
|
||||
--registry REGISTRY \
|
||||
--org ORG \
|
||||
--repo REPO \
|
||||
--service "SERVICE_NAME:DOCKERFILE_PATH" \
|
||||
--service "SERVICE_NAME:DOCKERFILE_PATH" \
|
||||
--branches "main,develop" \
|
||||
--depends-on "BUILD_STEP_NAME" \
|
||||
[--build-arg "SERVICE:KEY=VALUE"] \
|
||||
[--npm-package "@scope/pkg:path" --npm-registry "URL"]
|
||||
```
|
||||
|
||||
### 3c. Present generated YAML
|
||||
|
||||
Show the full YAML output to the user and ask for confirmation before appending to `.woodpecker.yml`.
|
||||
|
||||
### 3d. Append to pipeline
|
||||
|
||||
Append the generated YAML to the end of `.woodpecker.yml`. The kaniko_setup anchor goes in the `variables:` section.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Secrets Checklist
|
||||
|
||||
Present the required Woodpecker secrets and commands to configure them:
|
||||
|
||||
```
|
||||
=== Required Woodpecker Secrets ===
|
||||
|
||||
Configure these at: https://WOODPECKER_HOST/repos/ORG/REPO/settings/secrets
|
||||
|
||||
1. gitea_username
|
||||
Value: Your Gitea username or service account
|
||||
Events: push, manual, tag
|
||||
|
||||
2. gitea_token
|
||||
Value: Gitea token with package:write scope
|
||||
Generate at: https://REGISTRY_HOST/user/settings/applications
|
||||
Events: push, manual, tag
|
||||
|
||||
CLI commands:
|
||||
woodpecker secret add ORG/REPO --name gitea_username --value "USERNAME"
|
||||
woodpecker secret add ORG/REPO --name gitea_token --value "TOKEN"
|
||||
```
|
||||
|
||||
If npm publishing was selected, also list:
|
||||
|
||||
```
|
||||
3. npm_token (if using separate npm registry)
|
||||
Value: npm registry auth token
|
||||
Events: push, manual, tag
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Verification Checklist
|
||||
|
||||
Present this checklist for the user to follow after implementation:
|
||||
|
||||
```
|
||||
=== Verification Checklist ===
|
||||
|
||||
□ 1. Secrets configured in Woodpecker UI
|
||||
→ gitea_username and gitea_token set
|
||||
→ Token has package:write scope
|
||||
|
||||
□ 2. Update docker-compose.yml to use registry images
|
||||
→ Change: build: ./src/backend-api
|
||||
→ To: image: REGISTRY/ORG/SERVICE:${IMAGE_TAG:-dev}
|
||||
|
||||
□ 3. Push to develop branch and verify pipeline
|
||||
→ Quality gates pass
|
||||
→ Docker build steps run (only on main/develop)
|
||||
→ Images appear in Gitea Packages
|
||||
|
||||
□ 4. Verify package linking
|
||||
→ Images linked to repository on Gitea Packages tab
|
||||
→ If linking fails (404), link manually via Gitea web UI
|
||||
|
||||
□ 5. Test image pull
|
||||
→ docker login REGISTRY
|
||||
→ docker pull REGISTRY/ORG/SERVICE:dev
|
||||
|
||||
□ 6. Commit the pipeline changes
|
||||
→ git add .woodpecker.yml
|
||||
→ git commit -m "feat: Add Docker build/push/link to CI pipeline"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example Session
|
||||
|
||||
```
|
||||
User: /setup-cicd
|
||||
|
||||
Agent: Let me scan this project...
|
||||
|
||||
=== CI/CD Scan Results ===
|
||||
Registry: git.uscllc.com
|
||||
Organization: usc
|
||||
Repository: uconnect
|
||||
|
||||
Dockerfiles Found:
|
||||
1. src/backend-api/Dockerfile → backend-api
|
||||
2. src/web-portal/Dockerfile → web-portal
|
||||
3. src/ingest-api/Dockerfile → ingest-api
|
||||
4. src/heartbeat-collector/Dockerfile → heartbeat-collector
|
||||
5. src/field-agent/Dockerfile → field-agent
|
||||
6. src/egress-api/Dockerfile → egress-api
|
||||
|
||||
Existing Pipeline: .woodpecker.yml
|
||||
- Has build step: yes (build-all)
|
||||
- Has Docker steps: no
|
||||
|
||||
I have a few questions:
|
||||
|
||||
1. Which Dockerfiles should be built in CI?
|
||||
A. backend-api
|
||||
B. web-portal
|
||||
C. ingest-api
|
||||
...
|
||||
G. All of the above
|
||||
|
||||
User: 1G, 2A, 3A, 4A
|
||||
|
||||
Agent: Generating pipeline YAML...
|
||||
[shows YAML]
|
||||
Shall I append this to .woodpecker.yml?
|
||||
|
||||
User: Yes
|
||||
|
||||
Agent: Done. Here are the secrets you need to configure:
|
||||
[shows secrets checklist]
|
||||
[shows verification checklist]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- The generator script handles `$$` escaping for Woodpecker shell variables automatically
|
||||
- Package linking requires Gitea 1.24.0+ (the API endpoint was added in that version)
|
||||
- If the project has no existing `.woodpecker.yml`, suggest running `init-project.sh` first to set up quality gates
|
||||
- For the kaniko_setup anchor, the registry hostname must not include `https://` — just the bare hostname
|
||||
- Build context defaults to `.` (project root) for Dockerfiles under `apps/`, `src/`, or `packages/`. For other locations (like `docker/postgres/`), the context is the Dockerfile's parent directory.
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
name: mosaic-standards
|
||||
description: Load machine-wide Mosaic standards and enforce the repository lifecycle contract. Use at session start for any coding runtime (Codex, Claude, OpenCode, etc.).
|
||||
---
|
||||
|
||||
# Mosaic Standards
|
||||
|
||||
## Load Order
|
||||
|
||||
1. `~/.config/mosaic/STANDARDS.md`
|
||||
2. Repository `AGENTS.md`
|
||||
3. Repo-local `.mosaic/repo-hooks.sh` when present
|
||||
|
||||
## Session Lifecycle
|
||||
|
||||
- Start: `scripts/agent/session-start.sh`
|
||||
- Priority scan: `scripts/agent/critical.sh`
|
||||
- End: `scripts/agent/session-end.sh`
|
||||
|
||||
If wrappers are available, you may use:
|
||||
|
||||
- `mosaic-session-start`
|
||||
- `mosaic-critical`
|
||||
- `mosaic-session-end`
|
||||
|
||||
## Enforcement Rules
|
||||
|
||||
- Treat `~/.config/mosaic` as canonical for shared guides, tools, profiles, and skills.
|
||||
- Do not edit generated project views directly when the repo defines canonical data sources.
|
||||
- Pull/rebase before edits in shared repositories.
|
||||
- Run project verification commands before claiming completion.
|
||||
- Use non-destructive git workflow unless explicitly instructed otherwise.
|
||||
Reference in New Issue
Block a user