@1agh/maude 0.15.0

package/plugins/flow/templates/ai-skeleton/README.md

@@ -0,0 +1,46 @@
+# `.ai/` — Second Brain
+
+This folder is your project's persistent memory for the `flow` plugin. Plans, decisions, reviews, snapshots, and scenario evidence live here. Commands read from it; subagents write to it.
+
+## Top-level layout
+
+| Folder | Owner command | Purpose |
+| ------ | ------------- | ------- |
+| `state/` | `/flow:status`, `/flow:pause`, `/flow:resume` | Single source of truth for current workflow phase. `STATE.md` is durable; `HANDOFF.md` is transient (created on pause, deleted on resume). |
+| `plans/` | `/flow:plan`, `/flow:execute` | Feature plans with task lists. `archive/` holds completed plans. |
+| `decisions/` | `/flow:record-ddr` | Design Decision Records. Append-only, numbered, never deleted. |
+| `reviews/` | `/flow:review-code`, `/flow:record-retro` | Code review snapshots and retrospective notes from completed work. |
+| `scenarios/` | `/flow:scenario` | Cross-platform UI scenario specs + per-run report folders (screenshots, evidence). `_lib/` holds shared helpers. |
+| `logs/` | `/flow:validate`, `/flow:maintain-ai-health` | System-level audit logs (validation runs, infrastructure reviews). |
+| `dev-logs/` | manual | Dev journal — free-form notes, links, scratchpad. Optional. |
+| `browser/` | `agent-browser` skill | Web automation evidence — DOM snapshots, HAR captures. |
+| `device/` | `agent-device` skill | Native device automation evidence — accessibility snapshots, screenshots, traces. |
+| `context/` | `/flow:setup-codebase-map`, `/flow:setup-context` | Living snapshots of codebase architecture (auto-generated, refresh periodically). |
+| `business/` | manual | Domain knowledge, glossary, stakeholders, personas. Hand-curated. |
+| `docs/` | manual | Internal design docs, patterns, ADR-adjacent prose. |
+| `design-import/` | `/design:handoff` (design plugin) | Canvas artifacts in transit from `.design/` to production code. |
+| `templates/` | manual | Copy-paste starters for plans, reviews, etc. |
+
+## Per-project files
+
+These live at the root of `.ai/` (not in subfolders) and are referenced by `workflows.config.json` → `paths`:
+
+- `<name>-prd.md` — product requirements / brief
+- `<name>-design-system.md` — design system reference (look & feel, tokens, density)
+- `workflows.config.json` — config consumed by all flow commands and skills
+
+## Conventions
+
+- **Append-only history.** Decisions, reviews, scenario reports — never delete, only supersede.
+- **Filename = identity.** Match the slug of the work (e.g. `plans/onboarding-flow.md`, `decisions/DDR-007-edge-runtime.md`).
+- **Date-stamped reports.** Scenario runs go in `scenarios/<scenario-id>/<YYYY-MM-DD-HHMM>/report.md`.
+- **`<project>` placeholder.** Commands resolve `<project>` from `workflows.config.json` → `name`.
+
+## Bootstrapping
+
+Run `maude init` from your repo root to scaffold this skeleton (idempotent — never overwrites). Then run Anthropic's built-in `/init` to generate `CLAUDE.md` (conventions, build commands, project rules — auto-loaded every session), and create `.ai/<name>-prd.md` with your product brief.
+
+> Note: `maude init` does not write `CLAUDE.md` itself — that's `/init`'s job. The split:
+>
+> - **`CLAUDE.md`** — prose Claude reads every session (conventions, gotchas, "always do X"). Generated by `/init`. Target under 200 lines.
+> - **`.ai/workflows.config.json`** — structured machine-readable knobs. Scaffolded by `maude init`. Populated further by `/flow:init`.

package/plugins/flow/templates/ai-skeleton/business/README.md

@@ -0,0 +1,12 @@
+# Business
+
+Hand-curated domain knowledge. Not generated by commands — you write what's useful.
+
+## Suggested files
+
+- `glossary.md` — domain terms, with definitions.
+- `personas.md` — primary user roles, what they care about.
+- `stakeholders.md` — humans involved in decisions (PM, design lead, oncall, …).
+- `goals.md` — quarterly or annual targets.
+
+Commands like `/flow:plan` and the `ux-critic`-style skills will read these when present.

package/plugins/flow/templates/ai-skeleton/context/README.md

@@ -0,0 +1,12 @@
+# Context
+
+Living snapshots of the codebase architecture. Generated by `/flow:setup-codebase-map`; consumed by `/flow:plan`, `/flow:setup-context`, and subagents.
+
+## Key files
+
+- `codebase-map.md` — the canonical snapshot. Refreshed on a cadence (typically before non-trivial planning).
+
+## Conventions
+
+- **Overwrite, don't append.** Snapshots replace; if you need history, use git.
+- **Don't hand-edit.** Run the command. If output is wrong, fix the command or its skill.

package/plugins/flow/templates/ai-skeleton/decisions/README.md

@@ -0,0 +1,20 @@
+# Design Decision Records
+
+Permanent log of architectural and product decisions. Each DDR is a standalone markdown file following the template in the flow plugin's `commands/ddr.md`.
+
+## Index
+
+> Append-only. Newest at the top.
+
+<!-- DDRs go here, format:
+- [DDR-NNN: Title](DDR-NNN-title.md) — YYYY-MM-DD, tags
+-->
+
+## Rules
+
+- **Numbering:** zero-padded, three digits, sequential (DDR-001, DDR-002, …).
+- **Status:** `Accepted` once committed. `Proposed` only inside an open PR. `Superseded by DDR-NNN` when replaced.
+- **We never delete.** Superseded DDRs stay — they're the trail of how we got here.
+- **Cross-link:** the plan, the commit, and the new code that implements the decision should all link the DDR.
+
+How to create one: `/flow:record-ddr <title>`. How to find related ones: read this index, or `grep -l <tag> .ai/decisions/*.md`.

package/plugins/flow/templates/ai-skeleton/docs/README.md

@@ -0,0 +1,5 @@
+# Docs
+
+Internal design docs, patterns, ADR-adjacent prose. The home for "here's how we think about X."
+
+If a doc evolves into an official architectural decision, promote it to a DDR in `decisions/`.

package/plugins/flow/templates/ai-skeleton/logs/README.md

@@ -0,0 +1,13 @@
+# Logs
+
+System-level audit logs. Output of `/flow:validate`, `/flow:maintain-ai-health`, and other diagnostic commands.
+
+## Subfolders
+
+- `system-reviews/` — periodic infrastructure audits.
+- (add others as needed — `validate/`, `health/`, etc.)
+
+## Conventions
+
+- **Filename:** `YYYY-MM-DD-<topic>.md`.
+- **Append-only.** These are forensic records, not living docs.

package/plugins/flow/templates/ai-skeleton/plans/README.md

@@ -0,0 +1,16 @@
+# Plans
+
+Feature implementation plans. One file per feature, slug as filename (e.g. `onboarding-flow.md`).
+
+## Lifecycle
+
+1. `/flow:plan <feature>` — agent drafts the plan into `<feature>.md`, including task list, file touch map, scenarios.
+2. `/flow:execute` — agent works through the task list, ticking items as `[x]`.
+3. `/flow:done` — agent finalizes, runs validation, then moves the file to `archive/`.
+
+## Conventions
+
+- **Front matter:** `name`, `status` (`proposed | active | done | archived`), `created`, `decisions` (DDR IDs).
+- **Task IDs:** `T1, T2, …` so `/flow:resume` can re-enter mid-flow.
+- **Cross-links:** plan links to the PRD section it implements and to DDRs it depends on.
+- **Archive on `/flow:done`,** not on completion of the last task — `archive/` means "shipped, link permanent."

package/plugins/flow/templates/ai-skeleton/release-guide.md

@@ -0,0 +1,35 @@
+# Release Guide — PROJECT_NAME
+
+> Walked step-by-step by `/flow:release`. Each `##` heading is a step; bash blocks are candidate commands (the slash command asks before running each). Edit this file to match how **your** project actually releases — the runbook is plain Markdown, no schema.
+
+## Pre-flight
+
+- [ ] On `main` with clean working tree (`git status` empty)
+- [ ] Latest CI green on `main`
+- [ ] At least one `.changeset/*.md` (or equivalent) since previous tag
+- [ ] You have publish permissions for the package(s) being released
+
+## Version bump
+
+```bash
+# CHANGELOG_PROVIDER_VERSION_CMD
+```
+
+## Tag & push
+
+```bash
+# CHANGELOG_PROVIDER_TAG_CMD
+```
+
+## Publish
+
+```bash
+# CHANGELOG_PROVIDER_PUBLISH_CMD
+```
+
+## Post-release
+
+- [ ] Announce in #releases (Slack / Discord / etc.)
+- [ ] Update tracker tickets to `released` status
+- [ ] Bump dependent repos / docs site if applicable
+- [ ] Verify the published artifact (e.g. `npm view <pkg> version`, smoke install in scratch dir)

package/plugins/flow/templates/ai-skeleton/reviews/README.md

@@ -0,0 +1,15 @@
+# Reviews
+
+Code-review snapshots and retrospectives. Output of `/flow:review-code` and `/flow:record-retro`.
+
+## File naming
+
+- Code reviews: `YYYY-MM-DD-<feature-slug>.md`
+- Retrospectives: `YYYY-MM-DD-retro-<feature-slug>.md`
+
+## What goes here
+
+- Findings from pre-commit `/flow:review-code` (verdicts, suggestions, follow-ups).
+- Retro notes after `/flow:done` — what worked, what didn't, what to change in the workflow loop itself.
+
+These are durable. Don't truncate; later retros benefit from older patterns.

package/plugins/flow/templates/ai-skeleton/scenarios/README.md

@@ -0,0 +1,26 @@
+# Scenarios
+
+Cross-platform UI scenarios. One folder per scenario; per-run reports inside.
+
+## Layout
+
+```
+scenarios/
+├── _lib/                       — shared helpers (selectors, fixtures, env)
+└── <scenario-slug>/
+    ├── spec.md                 — what the flow does, success criteria, platform matrix
+    └── <YYYY-MM-DD-HHMM>/
+        ├── report.md           — TL;DR + per-platform pivot table + counter deltas
+        ├── web-desktop/        — screenshots, logs
+        ├── web-mobile/
+        ├── ios-phone/
+        └── android-phone/
+```
+
+## Conventions
+
+- **Scenario slug:** kebab-case, action-oriented (`coach-creates-recurring-practice`, `signup-via-invite`).
+- **Run timestamp:** local time of the run start. Latest run = lexicographically last folder.
+- **Report format:** owned by the `scenario` skill — see plugin docs.
+
+Run with `/flow:scenario <slug>` (registered scenarios) or `/flow:scenario <ad-hoc description>` (one-off).

package/plugins/flow/templates/ai-skeleton/state/STATE.md

@@ -0,0 +1,25 @@
+# Workflow State
+
+> The workflow-state skill in the flow plugin owns the schema and rules.
+
+**Workflow:** ad-hoc
+**Phase:** intake
+**Status:** ready
+**Started:** YYYY-MM-DD
+**Updated:** YYYY-MM-DD HH:MM
+**Active task:** —
+**Active plan:** —
+
+## Decisions
+
+- (none — full DDRs live in `.ai/decisions/`)
+
+## Blockers
+
+- (none)
+
+## History
+
+| When | Phase | Note |
+| ---- | ----- | ---- |
+|      |       |      |

package/plugins/flow/templates/ai-skeleton/templates/HANDOFF.md

@@ -0,0 +1,32 @@
+# HANDOFF
+
+> Transient file. Created on `/flow:pause`, removed on `/flow:resume`. Do not commit standalone.
+
+**Created:** YYYY-MM-DD HH:MM
+**Reason:** <why paused — end of session, context switch, blocker>
+
+## Active feature
+
+<name + path to plan>
+
+## Last task
+
+<T<n>: description, status>
+
+## Next step
+
+A concrete action. Command, file, line. Specific enough that the resumer can pick up directly.
+
+## Open questions / blockers
+
+- <bullet>
+
+## Files touched (uncommitted)
+
+```
+<git status --short output>
+```
+
+## Recent thinking
+
+1–2 paragraphs. Trail of thought, so the resumer can pick up the direction.

package/plugins/flow/templates/ai-skeleton/workflows.config.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "../../plugins/flow/.claude-plugin/config.schema.json",
+  "name": "PROJECT_NAME",
+  "language": "en",
+  "theme": "agnostic",
+  "paths": {
+    "prd": ".ai/PROJECT_NAME-prd.md",
+    "designSystem": ".ai/PROJECT_NAME-design-system.md",
+    "codebaseMap": ".ai/context/codebase-map.md"
+  },
+  "platforms": ["web-desktop"],
+  "stack": {
+    "language": "unknown",
+    "framework": "unknown",
+    "packageManager": "unknown",
+    "buildTool": "none",
+    "monorepo": false,
+    "ci": "unknown",
+    "tests": "unknown",
+    "css": "unknown",
+    "router": "unknown"
+  },
+  "conventions": {
+    "branchingModel": "github-flow",
+    "commits": "conventional",
+    "prohibited": []
+  },
+  "boundaries": {
+    "realtime": [],
+    "video": [],
+    "api": [],
+    "db": [],
+    "auth": [],
+    "telemetry": [],
+    "payments": []
+  },
+  "motion": {
+    "micro": 300,
+    "page": 500,
+    "complex": 1000,
+    "customPulses": {}
+  },
+  "responsive": {
+    "approach": "mobile-first",
+    "densityMap": {
+      "web-desktop": "cozy"
+    },
+    "breakpoints": { "sm": 480, "md": 768, "lg": 1024, "xl": 1280, "2xl": 1536 }
+  },
+  "ux": {
+    "responseTargetMs": 100,
+    "bilingual": []
+  },
+  "security": {
+    "severityFloor": "medium",
+    "scope": ["classic", "ai", "supply-chain"],
+    "includeAi": true
+  },
+  "skills": {
+    "motionRules": { "enabled": true },
+    "responsiveRules": { "enabled": true },
+    "a11yRules": { "enabled": true },
+    "testingRules": { "enabled": true },
+    "debuggingRules": { "enabled": true },
+    "securityRules": { "enabled": true }
+  },
+  "integrations": {
+    "tracker": { "provider": "none" },
+    "analytics": { "provider": "none" },
+    "ci": { "provider": "none" },
+    "design": { "provider": "none" },
+    "changelog": { "provider": "none" }
+  }
+}