diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md deleted file mode 100644 index 588a1c48..00000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,19 +0,0 @@ -# GitHub Copilot Instructions for Process-PSModule - -## Terminal Commands - -- Prefer MCP server calls over command-line tools when possible. -- When running scripts within the [scripts](../.specify/scripts/) folder, just run them directly (shell is default PowerShell). -- For other commands, send them into `pwsh -Command` to ensure proper execution. - -### Quoting in PowerShell - -Proper quoting is essential in PowerShell to prevent parsing errors and ensure correct command execution. - -- **Direct script execution**: Scripts run directly in PowerShell use standard PowerShell quoting rules. Double quotes expand variables and expressions, while single quotes are literal. No additional shell escaping is needed. - -- **Via `pwsh -Command`**: Commands are passed as strings to PowerShell. Enclose the entire command in single quotes to treat it as a literal string. Escape single quotes within the command by doubling them (e.g., `It's` becomes `It''s`). Use double quotes within the command for variable expansion, but ensure the outer single quotes protect the string from shell interpretation. - -For arguments containing single quotes, prefer double-quoting the argument inside the command string. - -Example: `pwsh -Command 'Write-Host "I''m Groot"'` diff --git a/.github/prompts/PSModule.analyze.prompt.md b/.github/prompts/PSModule.analyze.prompt.md deleted file mode 100644 index a3525777..00000000 --- a/.github/prompts/PSModule.analyze.prompt.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation. ---- - -# Analyze - -The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty). - -User input: - -$ARGUMENTS - -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 `/tasks` has successfully produced a complete `tasks.md`. - -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 `/analyze`. - -Execution steps: - -1. Run `.specify/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks` 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). - -2. Load artifacts: - - Parse spec.md sections: Overview/Context, Functional Requirements, Non-Functional Requirements, User Stories, Edge Cases (if present). - - Parse plan.md: Architecture/stack choices, Data Model references, Phases, Technical constraints. - - Parse tasks.md: Task IDs, descriptions, phase grouping, parallel markers [P], referenced file paths. - - Load constitution `.specify/memory/constitution.md` for principle validation. - -3. Build internal semantic models: - - Requirements inventory: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" -> `user-can-upload-file`). - - User story/action inventory. - - 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 any MUST/SHOULD normative statements. - -4. Detection passes: - 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, ???, , 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. - - Non-functional requirements not reflected in tasks (e.g., performance, security). - 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 to use Next.js while other says to use Vue as the framework). - -5. Severity assignment heuristic: - - 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, or untestable acceptance criterion. - - MEDIUM: Terminology drift, missing non-functional task coverage, or underspecified edge case. - - LOW: Style/wording improvements, or minor redundancy not affecting execution order. - -6. Produce a Markdown report (no file writes) with sections: - - ```markdown - ### 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.) - ``` - - Additional subsections: - - Coverage Summary Table: - - ```markdown - | 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. **Post issue comment** with analysis results organized by severity: - - Post a comment to the GitHub issue with the analysis findings - - Format the comment with separate tables for each severity level (only include levels that have findings): - ```markdown - ## Analysis Report - - ### Summary - - Total Requirements: X - - Total Tasks: Y - - Coverage: Z% - - Issues Found: N (A critical, B high, C medium, D low) - - ### Critical Issues - | ID | Category | Location(s) | Summary | Recommendation | - |----|----------|-------------|---------|----------------| - | C1 | ... | ... | ... | ... | - - ### High Priority Issues - | ID | Category | Location(s) | Summary | Recommendation | - |----|----------|-------------|---------|----------------| - | H1 | ... | ... | ... | ... | - - ### Medium Priority Issues - | ID | Category | Location(s) | Summary | Recommendation | - |----|----------|-------------|---------|----------------| - | M1 | ... | ... | ... | ... | - - ### Low Priority Issues - | ID | Category | Location(s) | Summary | Recommendation | - |----|----------|-------------|---------|----------------| - | L1 | ... | ... | ... | ... | - - ### Next Actions - - [Recommendation based on findings] - ``` - - Keep tables concise, limit to 20 findings per severity level - - If more than 20 findings in a category, add a note: "_(Additional N issues not shown - see full report)_" - - Include the complete "Next Actions" block with specific recommendations - -8. At end of report, output a concise Next Actions block: - - If CRITICAL issues exist: Recommend resolving them before `/implement`. - - If only LOW/MEDIUM issues: User may proceed, but provide improvement suggestions. - - Provide explicit command suggestions: e.g., "Run /specify with refinement", "Run /plan to adjust architecture", or "Manually edit tasks.md to add coverage for 'performance-metrics'". - -8. Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.) - -Behavior rules: -- NEVER modify files. -- NEVER hallucinate missing sections—if absent, report them. -- KEEP findings deterministic: if rerun without changes, produce consistent IDs and counts. -- LIMIT total findings in the main table to 50; aggregate remainder in a summarized overflow note. -- If zero issues found, emit a success report with coverage statistics and proceed recommendation. - -Context: $ARGUMENTS diff --git a/.github/prompts/PSModule.clarify.prompt.md b/.github/prompts/PSModule.clarify.prompt.md deleted file mode 100644 index ed8a26d0..00000000 --- a/.github/prompts/PSModule.clarify.prompt.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec. ---- - -# Clarify - -The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty). - -User input: - -$ARGUMENTS - -Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file. - -Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases. - -Execution steps: - -1. Run `.specify/scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields: - - `FEATURE_DIR` - - `FEATURE_SPEC` - - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.) - - If JSON parsing fails, abort and instruct user to re-run `/specify` or verify feature branch environment. - -2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked). - - Functional Scope & Behavior: - - Core user goals & success criteria - - Explicit out-of-scope declarations - - User roles / personas differentiation - - Domain & Data Model: - - Entities, attributes, relationships - - Identity & uniqueness rules - - Lifecycle/state transitions - - Data volume / scale assumptions - - Interaction & UX Flow: - - Critical user journeys / sequences - - Error/empty/loading states - - Accessibility or localization notes - - Non-Functional Quality Attributes: - - Performance (latency, throughput targets) - - Scalability (horizontal/vertical, limits) - - Reliability & availability (uptime, recovery expectations) - - Observability (logging, metrics, tracing signals) - - Security & privacy (authN/Z, data protection, threat assumptions) - - Compliance / regulatory constraints (if any) - - Integration & External Dependencies: - - External services/APIs and failure modes - - Data import/export formats - - Protocol/versioning assumptions - - Edge Cases & Failure Handling: - - Negative scenarios - - Rate limiting / throttling - - Conflict resolution (e.g., concurrent edits) - - Constraints & Tradeoffs: - - Technical constraints (language, storage, hosting) - - Explicit tradeoffs or rejected alternatives - - Terminology & Consistency: - - Canonical glossary terms - - Avoided synonyms / deprecated terms - - Completion Signals: - - Acceptance criteria testability - - Measurable Definition of Done style indicators - - Misc / Placeholders: - - TODO markers / unresolved decisions - - Ambiguous adjectives ("robust", "intuitive") lacking quantification - - For each category with Partial or Missing status, add a candidate question opportunity unless: - - Clarification would not materially change implementation or validation strategy - - Information is better deferred to planning phase (note internally) - -3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints: - - Maximum of 5 total questions across the entire session. - - Each question must be answerable with EITHER: - * A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR - * A one-word / short‑phrase answer (explicitly constrain: "Answer in ≤5 words"). - - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation. - - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved. - - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness). - - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests. - - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic. - -4. Sequential questioning loop (interactive): - - Present EXACTLY ONE question at a time. - - For multiple‑choice questions render options as a Markdown table: - - ```markdown - | Option | Description | - |--------|-------------| - | A |