Sync .cursor from suite (autodev orchestrator + monorepo skills)

.cursor/skills/plan/steps/06_work-item-epics.md

@@ -6,12 +6,22 @@
 
 **Constraints**: Epic descriptions must be **comprehensive and self-contained** — a developer reading only the epic should understand the full context without needing to open separate files.
 
+0. **Consult LESSONS.md** — if `_docs/LESSONS.md` exists, read it and factor any `estimation` / `architecture` / `dependencies` entries into epic sizing, scope, and dependency ordering. This closes the retrospective feedback loop; lessons from prior cycles directly inform current epic shape. Note in the Step 6 output which lessons were applied (or that none were relevant).
 1. **Create "Bootstrap & Initial Structure" epic first** — this epic will parent the `01_initial_structure` task created by the decompose skill. It covers project scaffolding: folder structure, shared models, interfaces, stubs, CI/CD config, DB migrations setup, test structure.
-2. Generate epics for each component using the configured work item tracker (see `autopilot/protocols.md` for tracker detection), structured per `templates/epic-spec.md`
-3. Order epics by dependency (Bootstrap epic is always first, then components based on their dependency graph)
-4. Include effort estimation per epic (T-shirt size or story points range)
-5. Ensure each epic has clear acceptance criteria cross-referenced with component specs
-6. Generate Mermaid diagrams showing component-to-epic mapping and component relationships
+2. **Identify cross-cutting concerns from architecture.md and restrictions.md**. Default candidates to consider (include only if architecture/restrictions reference them):
+   - Logging / observability (structured logging, correlation IDs, metrics)
+   - Error handling / envelope / result types
+   - Configuration loading (env vars, config files, secrets)
+   - Authentication / authorization middleware
+   - Feature flags / toggles
+   - Telemetry / tracing
+   - i18n / localization
+   For each identified concern, create ONE epic named `Cross-Cutting: <name>` with `epic_type: cross-cutting`. Each cross-cutting epic will parent exactly ONE shared implementation task (placed under `src/shared/<concern>/` by decompose skill). All component-level tasks that consume the concern declare the shared task as a dependency — they do NOT re-implement the concern locally. This rule is enforced by code-review Phase 6 (Cross-Task Consistency) and Phase 7 (Architecture Compliance).
+3. Generate epics for each component using the configured work item tracker (see `autodev/protocols.md` for tracker detection), structured per `templates/epic-spec.md`
+4. Order epics by dependency: Bootstrap epic first, then Cross-Cutting epics (they underlie everything), then component epics in dependency order
+5. Include effort estimation per epic (T-shirt size or story points range). Use LESSONS.md estimation entries as a calibration hint — if a lesson says "component X was underestimated by 2x last time" and the current plan has a comparable component, widen that epic's estimate.
+6. Ensure each epic has clear acceptance criteria cross-referenced with component specs
+7. Generate Mermaid diagrams showing component-to-epic mapping and component relationships; include cross-cutting epics as horizontal dependencies of every consuming component epic
 
 **CRITICAL — Epic description richness requirements**:
 
@@ -35,14 +45,17 @@ Do NOT create minimal epics with just a summary and short description. The epic
 
 **Self-verification**:
 - [ ] "Bootstrap & Initial Structure" epic exists and is first in order
+- [ ] Every identified cross-cutting concern has exactly one `Cross-Cutting: <name>` epic
+- [ ] No two epics own the same cross-cutting concern
 - [ ] "Blackbox Tests" epic exists
-- [ ] Every component maps to exactly one epic
+- [ ] Every component maps to exactly one component epic
 - [ ] Dependency order is respected (no epic depends on a later one)
+- [ ] Cross-Cutting epics precede every consuming component epic
 - [ ] Acceptance criteria are measurable
-- [ ] Effort estimates are realistic
+- [ ] Effort estimates are realistic and reflect LESSONS.md calibration hints (if any applied)
 - [ ] Every epic description includes architecture diagram, interface spec, data flow, risks, and NFRs
 - [ ] Epic descriptions are self-contained — readable without opening other files
 
-7. **Create "Blackbox Tests" epic** — this epic will parent the blackbox test tasks created by the `/decompose` skill. It covers implementing the test scenarios defined in `tests/`.
+8. **Create "Blackbox Tests" epic** — this epic will parent the blackbox test tasks created by the `/decompose` skill. It covers implementing the test scenarios defined in `tests/`.
 
 **Save action**: Epics created via the configured tracker MCP. Also saved locally in `epics.md` with ticket IDs. If `tracker: local`, save locally only.

.cursor/skills/plan/templates/epic-spec.md

@@ -1,6 +1,6 @@
 # Epic Template
 
-Use this template for each epic. Create epics via the configured work item tracker (see `autopilot/protocols.md` for tracker detection).
+Use this template for each epic. Create epics via the configured work item tracker (see `autodev/protocols.md` for tracker detection).
 
 ---
 
@@ -9,6 +9,9 @@ Use this template for each epic. Create epics via the configured work item track
 
 **Example**: Data Ingestion — Near-real-time pipeline
 
+**epic_type**: [component | bootstrap | cross-cutting | tests]
+**concern** (cross-cutting only): [logging | error-handling | config | authn | authz | feature-flags | telemetry | i18n | other-named-concern]
+
 ### Epic Summary
 
 [1-2 sentences: what we are building + why it matters]
@@ -123,5 +126,11 @@ Link to architecture.md and relevant component spec.]
 - Be concise. Fewer words with the same meaning = better epic.
 - Capabilities in scope are "what", not "how" — avoid describing implementation details.
 - Dependency order matters: epics that must be done first should be listed earlier in the backlog.
-- Every epic maps to exactly one component. If a component is too large for one epic, split the component first.
+- Every `component` epic maps to exactly one component. If a component is too large for one epic, split the component first.
+- A `cross-cutting` epic maps to exactly one shared concern and parents exactly one shared implementation task. Component epics that consume the concern declare the cross-cutting epic as a dependency.
+- Valid `epic_type` values:
+  - `bootstrap` — the initial-structure epic (always exactly one per project)
+  - `component` — a normal per-component epic
+  - `cross-cutting` — a shared concern that spans ≥2 components
+  - `tests` — the blackbox-tests epic (always exactly one)
 - Complexity points for child issues follow the project standard: 1, 2, 3, 5, 8. Do not create issues above 5 points — split them.