meshtastic
diff --git a/‎.github/agents/speckit.analyze.agent.md‎
Lines changed: 249 additions & 0 deletions b/‎.github/agents/speckit.analyze.agent.md‎
Lines changed: 249 additions & 0 deletions
diff --git a/‎.github/agents/speckit.brownfield.bootstrap.agent.md‎
Lines changed: 113 additions & 0 deletions b/‎.github/agents/speckit.brownfield.bootstrap.agent.md‎
Lines changed: 113 additions & 0 deletions
@@ -0,0 +1,249 @@
+---
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before analysis)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_analyze` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Goal.
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.md`.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements
+- Success Criteria (measurable outcomes — e.g., performance, security, availability, user success, business impact)
+- User Stories
+- Edge Cases (if present)
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Phases
+- Technical constraints
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `.specify/memory/constitution.md` for principle validation
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: For each Functional Requirement (FR-###) and Success Criterion (SC-###), record a stable key. Use the explicit FR-/SC- identifier as the primary key when present, and optionally also derive an imperative-phrase slug for readability (e.g., "User can upload file" → `user-can-upload-file`). Include only Success Criteria items that require buildable work (e.g., load-testing infrastructure, security audit tooling), and exclude post-launch outcome metrics and business KPIs (e.g., "Reduce support tickets by 50%").
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Success Criteria requiring buildable work (performance, security, availability) not reflected in tasks
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+## Specification Analysis Report
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+**Coverage Summary Table:**
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|-----------------|-----------|----------|-------|
+
+**Constitution Alignment Issues:** (if any)
+
+**Unmapped Tasks:** (if any)
+
+**Metrics:**
+
+- Total Requirements
+- Total Tasks
+- Coverage % (requirements with >=1 task)
+- Ambiguity Count
+- Duplication Count
+- Critical Issues Count
+
+### 7. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `/speckit.implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
+
+### 8. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+### 9. Check for extension hooks
+
+After reporting, check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.after_analyze` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+## Context
+
+$ARGUMENTS
@@ -0,0 +1,113 @@
+---
+description: Generate spec-kit configuration tailored to the existing codebase
+---
+
+
+<!-- Extension: brownfield -->
+<!-- Config: .specify/extensions/brownfield/ -->
+# Bootstrap Spec-Kit
+
+Generate a customized spec-kit configuration for an existing codebase. Uses the project profile from `/speckit.brownfield.scan` (or performs a scan if none exists) to create a constitution, templates, and agent configuration that match the project's actual architecture, tech stack, and conventions.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty). The user may specify preferences (e.g., "strict TDD", "minimal constitution"), a target directory for a monorepo module, or request specific template customizations.
+
+## Prerequisites
+
+1. Verify the current directory is a git repository
+2. Verify a spec-kit project exists by checking for `.specify/` directory (run `specify init` first if missing)
+3. Check if a project profile exists from a previous scan — if not, run a scan first
+
+## Outline
+
+1. **Load or generate project profile**: Check if `/speckit.brownfield.scan` has been run:
+   - If a project profile exists, use it
+   - If not, perform an inline scan to gather tech stack, architecture, and conventions
+   - Confirm the profile with the user before proceeding
+
+2. **Generate constitution**: Create `.specify/memory/constitution.md` tailored to the project:
+
+   The constitution **MUST** include:
+   - **Project identity**: Name, purpose, primary language(s), architecture pattern
+   - **Code boundaries**: Which directories contain which types of code (e.g., "frontend code lives in `client/`, backend in `server/`")
+   - **Naming conventions**: File naming, variable naming, branch naming as detected
+   - **Testing requirements**: Test framework, test location, coverage expectations
+   - **Dependency rules**: How modules depend on each other, what imports are allowed
+   - **Quality gates**: Linting, formatting, CI checks that must pass
+
+   The constitution **MUST NOT**:
+   - Override existing project standards without user confirmation
+   - Invent conventions that don't exist in the codebase
+   - Include generic boilerplate unrelated to the actual project
+
+3. **Customize spec template**: Modify `.specify/templates/spec-template.md` to reflect the project:
+   - Add project-specific sections (e.g., "Database Migrations" for projects with ORMs)
+   - Include architecture-aware requirements (e.g., "Frontend Requirements" and "API Requirements" for full-stack projects)
+   - Reference actual module paths instead of generic placeholders
+
+4. **Customize plan template**: Modify `.specify/templates/plan-template.md` to reflect the project:
+   - Include module-aware implementation sections (e.g., separate phases for frontend/backend)
+   - Reference actual test frameworks and build tools
+   - Include project-specific complexity factors
+
+5. **Customize tasks template**: Modify `.specify/templates/tasks-template.md` to reflect the project:
+   - Task phases should map to the project's actual module structure
+   - Include project-specific setup tasks (e.g., database migration, dependency install)
+   - Reference actual test commands (e.g., `npm test`, `pytest`, `go test ./...`)
+
+6. **Generate AGENTS.md** (if multi-module): For monorepos and multi-module projects:
+   - Define agent boundaries per module
+   - Specify which agent owns which directories
+   - Set up inter-agent communication rules
+
+7. **Present changes**: Show the user what will be created or modified:
+
+   ```markdown
+   # Bootstrap Plan
+
+   | File | Action | Description |
+   |------|--------|-------------|
+   | `.specify/memory/constitution.md` | Create | Project-specific constitution with detected conventions |
+   | `.specify/templates/spec-template.md` | Modify | Add project-specific sections (Database Migrations, API Contract) |
+   | `.specify/templates/plan-template.md` | Modify | Add module-aware phases (frontend, backend, shared) |
+   | `.specify/templates/tasks-template.md` | Modify | Add actual test commands and build steps |
+   | `AGENTS.md` | Create | Agent boundaries for frontend and backend modules |
+
+   Proceed with bootstrap? (confirm before writing)
+   ```
+
+8. **Execute bootstrap**: After user confirmation, write all files.
+
+9. **Report**:
+
+   ```markdown
+   # Bootstrap Complete
+
+   | Artifact | Status |
+   |----------|--------|
+   | Constitution | ✅ Created — 12 rules from detected conventions |
+   | Spec template | ✅ Customized — added Database Migrations, API Contract sections |
+   | Plan template | ✅ Customized — frontend/backend phase split |
+   | Tasks template | ✅ Customized — actual test commands included |
+   | AGENTS.md | ✅ Created — 2 agents (frontend, backend) |
+
+   ## Next Steps
+   - Review `.specify/memory/constitution.md` and adjust any rules
+   - Run `/speckit.brownfield.validate` to verify configuration matches project
+   - Run `/speckit.brownfield.migrate` to reverse-engineer specs for existing features
+   - Start new features with `/speckit.specify` — templates are now project-aware
+   ```
+
+## Rules
+
+- **Always confirm before writing** — show the bootstrap plan and wait for approval
+- **Never overwrite without asking** — if constitution or templates already exist, show a diff and ask
+- **Derive from reality** — every constitution rule must trace to something detected in the codebase
+- **No invented conventions** — if the project has no consistent pattern for something, say so instead of guessing
+- **Respect existing spec-kit setup** — if `.specify/` already has customizations, merge rather than replace
+- **Module-aware** — for monorepos, generate configuration that respects module boundaries