From c9d157d5d2a8d4195c9e80386b693cb8ff80656c Mon Sep 17 00:00:00 2001 From: Dariusz Porowski <3431813+DariuszPorowski@users.noreply.github.com> Date: Thu, 6 Nov 2025 13:27:16 -0800 Subject: [PATCH 1/2] feat(spec-kit): add powershell support Signed-off-by: Dariusz Porowski <3431813+DariuszPorowski@users.noreply.github.com> --- .github/prompts/speckit.analyze.prompt.md | 10 +- .github/prompts/speckit.checklist.prompt.md | 27 +- .github/prompts/speckit.clarify.prompt.md | 2 +- .../prompts/speckit.constitution.prompt.md | 8 +- .github/prompts/speckit.implement.prompt.md | 22 +- .github/prompts/speckit.plan.prompt.md | 10 +- .github/prompts/speckit.specify.prompt.md | 251 +++++----- .github/prompts/speckit.tasks.prompt.md | 10 +- .../powershell/check-prerequisites.ps1 | 150 ++++++ .specify/scripts/powershell/common.ps1 | 142 ++++++ .../scripts/powershell/create-new-feature.ps1 | 290 ++++++++++++ .specify/scripts/powershell/setup-plan.ps1 | 64 +++ .../powershell/update-agent-context.ps1 | 439 ++++++++++++++++++ 13 files changed, 1286 insertions(+), 139 deletions(-) create mode 100644 .specify/scripts/powershell/check-prerequisites.ps1 create mode 100644 .specify/scripts/powershell/common.ps1 create mode 100644 .specify/scripts/powershell/create-new-feature.ps1 create mode 100644 .specify/scripts/powershell/setup-plan.ps1 create mode 100644 .specify/scripts/powershell/update-agent-context.ps1 diff --git a/.github/prompts/speckit.analyze.prompt.md b/.github/prompts/speckit.analyze.prompt.md index 98b04b0c..3cb2545b 100644 --- a/.github/prompts/speckit.analyze.prompt.md +++ b/.github/prompts/speckit.analyze.prompt.md @@ -24,7 +24,7 @@ Identify inconsistencies, duplications, ambiguities, and underspecified items ac ### 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: +Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` (Linux or macOS) or `.specify/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks` (Windows) 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 @@ -126,16 +126,16 @@ 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 | +| 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) diff --git a/.github/prompts/speckit.checklist.prompt.md b/.github/prompts/speckit.checklist.prompt.md index 970e6c9e..7c2bcd31 100644 --- a/.github/prompts/speckit.checklist.prompt.md +++ b/.github/prompts/speckit.checklist.prompt.md @@ -33,17 +33,20 @@ You **MUST** consider the user input before proceeding (if not empty). ## Execution Steps -1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list. +1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` (Linux or macOS) or `.specify/scripts/powershell/check-prerequisites.ps1 -Json` (Windows) from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list. + - All file paths must be absolute. - 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. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST: + - Be generated from the user's phrasing + extracted signals from spec/plan/tasks - Only ask about information that materially changes checklist content - Be skipped individually if already unambiguous in `$ARGUMENTS` - Prefer precision over breadth Generation algorithm: + 1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts"). 2. Cluster signals into candidate focus areas (max 4) ranked by relevance. 3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit. @@ -57,12 +60,14 @@ You **MUST** consider the user input before proceeding (if not empty). - Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?") Question formatting rules: + - If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters - Limit to A–E options maximum; omit table if a free-form answer is clearer - Never ask the user to restate what they already said - Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope." Defaults when interaction impossible: + - Depth: Standard - Audience: Reviewer (PR) if code-related; Author otherwise - Focus: Top 2 relevance clusters @@ -70,23 +75,27 @@ You **MUST** consider the user input before proceeding (if not empty). Output the questions (label Q1/Q2/Q3). After answers: if ≥2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more. 3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers: + - Derive checklist theme (e.g., security, review, deploy, ux) - Consolidate explicit must-have items mentioned by user - Map focus selections to category scaffolding - Infer any missing context from spec/plan/tasks (do NOT hallucinate) 4. **Load feature context**: Read from FEATURE_DIR: + - spec.md: Feature requirements and scope - plan.md (if exists): Technical details, dependencies - tasks.md (if exists): Implementation tasks **Context Loading Strategy**: + - Load only necessary portions relevant to active focus areas (avoid full-file dumping) - Prefer summarizing long sections into concise scenario/requirement bullets - Use progressive disclosure: add follow-on retrieval only if gaps detected - If source docs are large, generate interim summary items instead of embedding raw text 5. **Generate checklist** - Create "Unit Tests for Requirements": + - Create `FEATURE_DIR/checklists/` directory if it doesn't exist - Generate unique checklist filename: - Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`) @@ -97,6 +106,7 @@ You **MUST** consider the user input before proceeding (if not empty). **CORE PRINCIPLE - Test the Requirements, Not the Implementation**: Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for: + - **Completeness**: Are all necessary requirements present? - **Clarity**: Are requirements unambiguous and specific? - **Consistency**: Do requirements align with each other? @@ -104,6 +114,7 @@ You **MUST** consider the user input before proceeding (if not empty). - **Coverage**: Are all scenarios/edge cases addressed? **Category Structure** - Group items by requirement quality dimensions: + - **Requirement Completeness** (Are all necessary requirements documented?) - **Requirement Clarity** (Are requirements specific and unambiguous?) - **Requirement Consistency** (Do requirements align without conflicts?) @@ -117,11 +128,13 @@ You **MUST** consider the user input before proceeding (if not empty). **HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**: ❌ **WRONG** (Testing implementation): + - "Verify landing page displays 3 episode cards" - "Test hover states work on desktop" - "Confirm logo click navigates home" ✅ **CORRECT** (Testing requirements quality): + - "Are the exact number and layout of featured episodes specified?" [Completeness] - "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity] - "Are hover state requirements consistent across all interactive elements?" [Consistency] @@ -132,6 +145,7 @@ You **MUST** consider the user input before proceeding (if not empty). **ITEM STRUCTURE**: Each item should follow this pattern: + - Question format asking about requirement quality - Focus on what's WRITTEN (or not written) in the spec/plan - Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.] @@ -141,41 +155,49 @@ You **MUST** consider the user input before proceeding (if not empty). **EXAMPLES BY QUALITY DIMENSION**: Completeness: + - "Are error handling requirements defined for all API failure modes? [Gap]" - "Are accessibility requirements specified for all interactive elements? [Completeness]" - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]" Clarity: + - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]" - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]" - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]" Consistency: + - "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]" - "Are card component requirements consistent between landing and detail pages? [Consistency]" Coverage: + - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]" - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]" - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]" Measurability: + - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]" - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]" **Scenario Classification & Coverage** (Requirements Quality Focus): + - Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios - For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?" - If scenario class missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]" - Include resilience/rollback when state mutation occurs: "Are rollback requirements defined for migration failures? [Gap]" **Traceability Requirements**: + - MINIMUM: ≥80% of items MUST include at least one traceability reference - Each item should reference: spec section `[Spec §X.Y]`, or use markers: `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]` - If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]" **Surface & Resolve Issues** (Requirements Quality Problems): Ask questions about the requirements themselves: + - Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]" - Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]" - Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]" @@ -183,11 +205,13 @@ You **MUST** consider the user input before proceeding (if not empty). - Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]" **Content Consolidation**: + - Soft cap: If raw candidate items > 40, prioritize by risk/impact - Merge near-duplicates checking the same requirement aspect - If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]" **🚫 ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test: + - ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior - ❌ References to code execution, user actions, system behavior - ❌ "Displays correctly", "works properly", "functions as expected" @@ -196,6 +220,7 @@ You **MUST** consider the user input before proceeding (if not empty). - ❌ Implementation details (frameworks, APIs, algorithms) **✅ REQUIRED PATTERNS** - These test requirements quality: + - ✅ "Are [requirement type] defined/specified/documented for [scenario]?" - ✅ "Is [vague term] quantified/clarified with specific criteria?" - ✅ "Are requirements consistent between [section A] and [section B]?" diff --git a/.github/prompts/speckit.clarify.prompt.md b/.github/prompts/speckit.clarify.prompt.md index 8ff62c34..382e805a 100644 --- a/.github/prompts/speckit.clarify.prompt.md +++ b/.github/prompts/speckit.clarify.prompt.md @@ -18,7 +18,7 @@ Note: This clarification workflow is expected to run (and be completed) BEFORE i Execution steps: -1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields: +1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` (Linux or macOS) `.specify/scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly` (Windows) 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.) diff --git a/.github/prompts/speckit.constitution.prompt.md b/.github/prompts/speckit.constitution.prompt.md index f37fb058..6f57e67e 100644 --- a/.github/prompts/speckit.constitution.prompt.md +++ b/.github/prompts/speckit.constitution.prompt.md @@ -17,10 +17,12 @@ You are updating the project constitution at `.specify/memory/constitution.md`. Follow this execution flow: 1. Load the existing constitution template at `.specify/memory/constitution.md`. + - Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`. - **IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly. + **IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly. 2. Collect/derive values for placeholders: + - If user input (conversation) supplies a value, use it. - Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded). - For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous. @@ -31,12 +33,14 @@ Follow this execution flow: - If version bump type ambiguous, propose reasoning before finalizing. 3. Draft the updated constitution content: + - Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left). - Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance. - Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious. - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations. 4. Consistency propagation checklist (convert prior checklist into active validations): + - Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles. - Read `.specify/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints. - Read `.specify/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline). @@ -44,6 +48,7 @@ Follow this execution flow: - Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed. 5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update): + - Version change: old → new - List of modified principles (old title → new title if renamed) - Added sections @@ -52,6 +57,7 @@ Follow this execution flow: - Follow-up TODOs if any placeholders intentionally deferred. 6. Validation before final output: + - No remaining unexplained bracket tokens. - Version line matches report. - Dates ISO format YYYY-MM-DD. diff --git a/.github/prompts/speckit.implement.prompt.md b/.github/prompts/speckit.implement.prompt.md index 9646a2d8..0ceb26e5 100644 --- a/.github/prompts/speckit.implement.prompt.md +++ b/.github/prompts/speckit.implement.prompt.md @@ -12,9 +12,10 @@ You **MUST** consider the user input before proceeding (if not empty). ## Outline -1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. 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"). +1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` (Linux or macOS) or `.specify/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks` (Windows) from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. 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. **Check checklists status** (if FEATURE_DIR/checklists/ exists): + - Scan all checklist files in the checklists/ directory - For each checklist, count: - Total items: All lines matching `- [ ]` or `- [X]` or `- [x]` @@ -31,10 +32,12 @@ You **MUST** consider the user input before proceeding (if not empty). ``` - Calculate overall status: + - **PASS**: All checklists have 0 incomplete items - **FAIL**: One or more checklists have incomplete items - **If any checklist is incomplete**: + - Display the table with incomplete item counts - **STOP** and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)" - Wait for user response before continuing @@ -46,6 +49,7 @@ You **MUST** consider the user input before proceeding (if not empty). - Automatically proceed to step 3 3. Load and analyze the implementation context: + - **REQUIRED**: Read tasks.md for the complete task list and execution plan - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure - **IF EXISTS**: Read data-model.md for entities and relationships @@ -54,26 +58,29 @@ You **MUST** consider the user input before proceeding (if not empty). - **IF EXISTS**: Read quickstart.md for integration scenarios 4. **Project Setup Verification**: + - **REQUIRED**: Create/verify ignore files based on actual project setup: **Detection & Creation Logic**: + - Check if the following command succeeds to determine if the repository is a git repo (create/verify .gitignore if so): ```sh git rev-parse --git-dir 2>/dev/null ``` - - Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore + - Check if Dockerfile\* exists or Docker in plan.md → create/verify .dockerignore - Check if .eslintrc*or eslint.config.* exists → create/verify .eslintignore - - Check if .prettierrc* exists → create/verify .prettierignore + - Check if .prettierrc\* exists → create/verify .prettierignore - Check if .npmrc or package.json exists → create/verify .npmignore (if publishing) - - Check if terraform files (*.tf) exist → create/verify .terraformignore + - Check if terraform files (\*.tf) exist → create/verify .terraformignore - Check if .helmignore needed (helm charts present) → create/verify .helmignore **If ignore file already exists**: Verify it contains essential patterns, append missing critical patterns only **If ignore file missing**: Create with full pattern set for detected technology **Common Patterns by Technology** (from plan.md tech stack): + - **Node.js/JavaScript/TypeScript**: `node_modules/`, `dist/`, `build/`, `*.log`, `.env*` - **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `dist/`, `*.egg-info/` - **Java**: `target/`, `*.class`, `*.jar`, `.gradle/`, `build/` @@ -90,6 +97,7 @@ You **MUST** consider the user input before proceeding (if not empty). - **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/` **Tool-Specific Patterns**: + - **Docker**: `node_modules/`, `.git/`, `Dockerfile*`, `.dockerignore`, `*.log*`, `.env*`, `coverage/` - **ESLint**: `node_modules/`, `dist/`, `build/`, `coverage/`, `*.min.js` - **Prettier**: `node_modules/`, `dist/`, `build/`, `coverage/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` @@ -97,19 +105,22 @@ You **MUST** consider the user input before proceeding (if not empty). - **Kubernetes/k8s**: `*.secret.yaml`, `secrets/`, `.kube/`, `kubeconfig*`, `*.key`, `*.crt` 5. Parse tasks.md structure and extract: + - **Task phases**: Setup, Tests, Core, Integration, Polish - **Task dependencies**: Sequential vs parallel execution rules - **Task details**: ID, description, file paths, parallel markers [P] - **Execution flow**: Order and dependency requirements 6. Execute implementation following the task plan: + - **Phase-by-phase execution**: Complete each phase before moving to the next - - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together + - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks - **File-based coordination**: Tasks affecting the same files must run sequentially - **Validation checkpoints**: Verify each phase completion before proceeding 7. Implementation execution rules: + - **Setup first**: Initialize project structure, dependencies, configuration - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios - **Core development**: Implement models, services, CLI commands, endpoints @@ -117,6 +128,7 @@ You **MUST** consider the user input before proceeding (if not empty). - **Polish and validation**: Unit tests, performance optimization, documentation 8. Progress tracking and error handling: + - Report progress after each completed task - Halt execution if any non-parallel task fails - For parallel tasks [P], continue with successful tasks, report failed ones diff --git a/.github/prompts/speckit.plan.prompt.md b/.github/prompts/speckit.plan.prompt.md index e76c60a1..1dfeab7e 100644 --- a/.github/prompts/speckit.plan.prompt.md +++ b/.github/prompts/speckit.plan.prompt.md @@ -12,11 +12,12 @@ You **MUST** consider the user input before proceeding (if not empty). ## Outline -1. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. 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"). +1. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` (Linux or macOS) or `.specify/scripts/powershell/setup-plan.ps1 -Json` (Windows) from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. 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 context**: Read FEATURE_SPEC and `.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied). 3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to: + - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION") - Fill Constitution Check section from constitution - Evaluate gates (ERROR if violations unjustified) @@ -32,6 +33,7 @@ You **MUST** consider the user input before proceeding (if not empty). ### Phase 0: Outline & Research 1. **Extract unknowns from Technical Context** above: + - For each NEEDS CLARIFICATION → research task - For each dependency → best practices task - For each integration → patterns task @@ -57,23 +59,25 @@ You **MUST** consider the user input before proceeding (if not empty). **Prerequisites:** `research.md` complete 1. **Extract entities from feature spec** → `data-model.md`: + - Entity name, fields, relationships - Validation rules from requirements - State transitions if applicable 2. **Generate API contracts** from functional requirements: + - For each user action → endpoint - Use standard REST/GraphQL patterns - Output OpenAPI/GraphQL schema to `/contracts/` 3. **Agent context update**: - - Run `.specify/scripts/bash/update-agent-context.sh copilot` + - Run `.specify/scripts/bash/update-agent-context.sh copilot` (Linux or macOS) or `.specify/scripts/powershell/update-agent-context.ps1 -AgentType copilot` (Windows) - These scripts detect which AI agent is in use - Update the appropriate agent-specific context file - Add only new technology from current plan - Preserve manual additions between markers -**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific file +**Output**: data-model.md, /contracts/\*, quickstart.md, agent-specific file ## Key rules diff --git a/.github/prompts/speckit.specify.prompt.md b/.github/prompts/speckit.specify.prompt.md index e5b384c2..c9c22c27 100644 --- a/.github/prompts/speckit.specify.prompt.md +++ b/.github/prompts/speckit.specify.prompt.md @@ -17,6 +17,7 @@ The text the user typed after `/speckit.specify` in the triggering message **is* Given that feature description, do this: 1. **Generate a concise short name** (2-4 words) for the branch: + - Analyze the feature description and extract the most meaningful keywords - Create a 2-4 word short name that captures the essence of the feature - Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug") @@ -29,28 +30,33 @@ Given that feature description, do this: - "Fix payment processing timeout bug" → "fix-payment-timeout" 2. **Check for existing branches before creating new one**: - + a. First, fetch all remote branches to ensure we have the latest information: - ```bash - git fetch --all --prune - ``` - + + ```bash + git fetch --all --prune + ``` + b. Find the highest feature number across all sources for the short-name: - - Remote branches: `git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-$'` - - Local branches: `git branch | grep -E '^[* ]*[0-9]+-$'` - - Specs directories: Check for directories matching `specs/[0-9]+-` - + + - Remote branches: `git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-$'` + - Local branches: `git branch | grep -E '^[* ]*[0-9]+-$'` + - Specs directories: Check for directories matching `specs/[0-9]+-` + c. Determine the next available number: - - Extract all numbers from all three sources - - Find the highest number N - - Use N+1 for the new branch number - - d. Run the script `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"` with the calculated number and short-name: - - Pass `--number N+1` and `--short-name "your-short-name"` along with the feature description - - Bash example: `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" --json --number 5 --short-name "user-auth" "Add user authentication"` - - PowerShell example: `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" -Json -Number 5 -ShortName "user-auth" "Add user authentication"` - + + - Extract all numbers from all three sources + - Find the highest number N + - Use N+1 for the new branch number + + d. Run the script `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"` (Linux or macOS) or `.specify/scripts/powershell/create-new-feature.ps1 -Json "$ARGUMENTS"` (Windows) with the calculated number and short-name: + + - Pass `--number N+1` and `--short-name "your-short-name"` along with the feature description + - Bash example: `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" --json --number 5 --short-name "user-auth" "Add user authentication"` + - PowerShell example: `.specify/scripts/powershell/create-new-feature.ps1 -Json "$ARGUMENTS" -Json -Number 5 -ShortName "user-auth" "Add user authentication"` + **IMPORTANT**: + - Check all three sources (remote branches, local branches, specs directories) to find the highest number - Only match branches/directories with the exact short-name pattern - If no existing branches/directories found with this short-name, start with number 1 @@ -63,29 +69,29 @@ Given that feature description, do this: 4. Follow this execution flow: - 1. Parse user description from Input - If empty: ERROR "No feature description provided" - 2. Extract key concepts from description - Identify: actors, actions, data, constraints - 3. For unclear aspects: - - Make informed guesses based on context and industry standards - - Only mark with [NEEDS CLARIFICATION: specific question] if: - - The choice significantly impacts feature scope or user experience - - Multiple reasonable interpretations exist with different implications - - No reasonable default exists - - **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total** - - Prioritize clarifications by impact: scope > security/privacy > user experience > technical details - 4. Fill User Scenarios & Testing section - If no clear user flow: ERROR "Cannot determine user scenarios" - 5. Generate Functional Requirements - Each requirement must be testable - Use reasonable defaults for unspecified details (document assumptions in Assumptions section) - 6. Define Success Criteria - Create measurable, technology-agnostic outcomes - Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion) - Each criterion must be verifiable without implementation details - 7. Identify Key Entities (if data involved) - 8. Return: SUCCESS (spec ready for planning) + 1. Parse user description from Input + If empty: ERROR "No feature description provided" + 2. Extract key concepts from description + Identify: actors, actions, data, constraints + 3. For unclear aspects: + - Make informed guesses based on context and industry standards + - Only mark with [NEEDS CLARIFICATION: specific question] if: + - The choice significantly impacts feature scope or user experience + - Multiple reasonable interpretations exist with different implications + - No reasonable default exists + - **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total** + - Prioritize clarifications by impact: scope > security/privacy > user experience > technical details + 4. Fill User Scenarios & Testing section + If no clear user flow: ERROR "Cannot determine user scenarios" + 5. Generate Functional Requirements + Each requirement must be testable + Use reasonable defaults for unspecified details (document assumptions in Assumptions section) + 6. Define Success Criteria + Create measurable, technology-agnostic outcomes + Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion) + Each criterion must be verifiable without implementation details + 7. Identify Key Entities (if data involved) + 8. Return: SUCCESS (spec ready for planning) 5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings. @@ -93,91 +99,94 @@ Given that feature description, do this: a. **Create Spec Quality Checklist**: Generate a checklist file at `FEATURE_DIR/checklists/requirements.md` using the checklist template structure with these validation items: - ```markdown - # Specification Quality Checklist: [FEATURE NAME] - - **Purpose**: Validate specification completeness and quality before proceeding to planning - **Created**: [DATE] - **Feature**: [Link to spec.md] - - ## Content Quality - - - [ ] No implementation details (languages, frameworks, APIs) - - [ ] Focused on user value and business needs - - [ ] Written for non-technical stakeholders - - [ ] All mandatory sections completed - - ## Requirement Completeness - - - [ ] No [NEEDS CLARIFICATION] markers remain - - [ ] Requirements are testable and unambiguous - - [ ] Success criteria are measurable - - [ ] Success criteria are technology-agnostic (no implementation details) - - [ ] All acceptance scenarios are defined - - [ ] Edge cases are identified - - [ ] Scope is clearly bounded - - [ ] Dependencies and assumptions identified - - ## Feature Readiness - - - [ ] All functional requirements have clear acceptance criteria - - [ ] User scenarios cover primary flows - - [ ] Feature meets measurable outcomes defined in Success Criteria - - [ ] No implementation details leak into specification - - ## Notes - - - Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan` - ``` + ```markdown + # Specification Quality Checklist: [FEATURE NAME] + + **Purpose**: Validate specification completeness and quality before proceeding to planning + **Created**: [DATE] + **Feature**: [Link to spec.md] + + ## Content Quality + + - [ ] No implementation details (languages, frameworks, APIs) + - [ ] Focused on user value and business needs + - [ ] Written for non-technical stakeholders + - [ ] All mandatory sections completed + + ## Requirement Completeness + + - [ ] No [NEEDS CLARIFICATION] markers remain + - [ ] Requirements are testable and unambiguous + - [ ] Success criteria are measurable + - [ ] Success criteria are technology-agnostic (no implementation details) + - [ ] All acceptance scenarios are defined + - [ ] Edge cases are identified + - [ ] Scope is clearly bounded + - [ ] Dependencies and assumptions identified + + ## Feature Readiness + + - [ ] All functional requirements have clear acceptance criteria + - [ ] User scenarios cover primary flows + - [ ] Feature meets measurable outcomes defined in Success Criteria + - [ ] No implementation details leak into specification + + ## Notes + + - Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan` + ``` b. **Run Validation Check**: Review the spec against each checklist item: - - For each item, determine if it passes or fails - - Document specific issues found (quote relevant spec sections) + + - For each item, determine if it passes or fails + - Document specific issues found (quote relevant spec sections) c. **Handle Validation Results**: - - **If all items pass**: Mark checklist complete and proceed to step 6 - - - **If items fail (excluding [NEEDS CLARIFICATION])**: - 1. List the failing items and specific issues - 2. Update the spec to address each issue - 3. Re-run validation until all items pass (max 3 iterations) - 4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user - - - **If [NEEDS CLARIFICATION] markers remain**: - 1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec - 2. **LIMIT CHECK**: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest - 3. For each clarification needed (max 3), present options to user in this format: - - ```markdown - ## Question [N]: [Topic] - - **Context**: [Quote relevant spec section] - - **What we need to know**: [Specific question from NEEDS CLARIFICATION marker] - - **Suggested Answers**: - - | Option | Answer | Implications | - |--------|--------|--------------| - | A | [First suggested answer] | [What this means for the feature] | - | B | [Second suggested answer] | [What this means for the feature] | - | C | [Third suggested answer] | [What this means for the feature] | - | Custom | Provide your own answer | [Explain how to provide custom input] | - - **Your choice**: _[Wait for user response]_ - ``` - - 4. **CRITICAL - Table Formatting**: Ensure markdown tables are properly formatted: - - Use consistent spacing with pipes aligned - - Each cell should have spaces around content: `| Content |` not `|Content|` - - Header separator must have at least 3 dashes: `|--------|` - - Test that the table renders correctly in markdown preview - 5. Number questions sequentially (Q1, Q2, Q3 - max 3 total) - 6. Present all questions together before waiting for responses - 7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B") - 8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer - 9. Re-run validation after all clarifications are resolved + - **If all items pass**: Mark checklist complete and proceed to step 6 + + - **If items fail (excluding [NEEDS CLARIFICATION])**: + + 1. List the failing items and specific issues + 2. Update the spec to address each issue + 3. Re-run validation until all items pass (max 3 iterations) + 4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user + + - **If [NEEDS CLARIFICATION] markers remain**: + + 1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec + 2. **LIMIT CHECK**: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest + 3. For each clarification needed (max 3), present options to user in this format: + + ```markdown + ## Question [N]: [Topic] + + **Context**: [Quote relevant spec section] + + **What we need to know**: [Specific question from NEEDS CLARIFICATION marker] + + **Suggested Answers**: + + | Option | Answer | Implications | + | ------ | ------------------------- | ------------------------------------- | + | A | [First suggested answer] | [What this means for the feature] | + | B | [Second suggested answer] | [What this means for the feature] | + | C | [Third suggested answer] | [What this means for the feature] | + | Custom | Provide your own answer | [Explain how to provide custom input] | + + **Your choice**: _[Wait for user response]_ + ``` + + 4. **CRITICAL - Table Formatting**: Ensure markdown tables are properly formatted: + - Use consistent spacing with pipes aligned + - Each cell should have spaces around content: `| Content |` not `|Content|` + - Header separator must have at least 3 dashes: `|--------|` + - Test that the table renders correctly in markdown preview + 5. Number questions sequentially (Q1, Q2, Q3 - max 3 total) + 6. Present all questions together before waiting for responses + 7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B") + 8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer + 9. Re-run validation after all clarifications are resolved d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status diff --git a/.github/prompts/speckit.tasks.prompt.md b/.github/prompts/speckit.tasks.prompt.md index 3b89c8ec..6e147223 100644 --- a/.github/prompts/speckit.tasks.prompt.md +++ b/.github/prompts/speckit.tasks.prompt.md @@ -12,14 +12,16 @@ You **MUST** consider the user input before proceeding (if not empty). ## Outline -1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. 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"). +1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` (Linux or macOS) or `.specify/scripts/powershell/check-prerequisites.ps1 -Json` (Windows) from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. 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 design documents**: Read from FEATURE_DIR: + - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities) - **Optional**: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios) - Note: Not all projects have all documents. Generate tasks based on what's available. 3. **Execute task generation workflow**: + - Load plan.md and extract tech stack, libraries, project structure - Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.) - If data-model.md exists: Extract entities and map to user stories @@ -31,6 +33,7 @@ You **MUST** consider the user input before proceeding (if not empty). - Validate task completeness (each user story has all needed tasks, independently testable) 4. **Generate tasks.md**: Use `.specify.specify/templates/tasks-template.md` as structure, fill with: + - Correct feature name from plan.md - Phase 1: Setup tasks (project initialization) - Phase 2: Foundational tasks (blocking prerequisites for all user stories) @@ -77,7 +80,7 @@ Every task MUST strictly follow this format: 4. **[Story] label**: REQUIRED for user story phase tasks only - Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md) - Setup phase: NO story label - - Foundational phase: NO story label + - Foundational phase: NO story label - User Story phases: MUST have story label - Polish phase: NO story label 5. **Description**: Clear action with exact file path @@ -96,6 +99,7 @@ Every task MUST strictly follow this format: ### Task Organization 1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION: + - Each user story (P1, P2, P3...) gets its own phase - Map all related components to their story: - Models needed for that story @@ -105,10 +109,12 @@ Every task MUST strictly follow this format: - Mark story dependencies (most stories should be independent) 2. **From Contracts**: + - Map each contract/endpoint → to the user story it serves - If tests requested: Each contract → contract test task [P] before implementation in that story's phase 3. **From Data Model**: + - Map each entity to the user story(ies) that need it - If entity serves multiple stories: Put in earliest story or Setup phase - Relationships → service layer tasks in appropriate story phase diff --git a/.specify/scripts/powershell/check-prerequisites.ps1 b/.specify/scripts/powershell/check-prerequisites.ps1 new file mode 100644 index 00000000..101a0ba9 --- /dev/null +++ b/.specify/scripts/powershell/check-prerequisites.ps1 @@ -0,0 +1,150 @@ +#!/usr/bin/env pwsh + +# Consolidated prerequisite checking script (PowerShell) +# +# This script provides unified prerequisite checking for Spec-Driven Development workflow. +# It replaces the functionality previously spread across multiple scripts. +# +# Usage: ./check-prerequisites.ps1 [OPTIONS] +# +# OPTIONS: +# -Json Output in JSON format +# -RequireTasks Require tasks.md to exist (for implementation phase) +# -IncludeTasks Include tasks.md in AVAILABLE_DOCS list +# -PathsOnly Only output path variables (no validation) +# -Help, -h Show help message + +[CmdletBinding()] +param( + [switch]$Json, + [switch]$RequireTasks, + [switch]$IncludeTasks, + [switch]$PathsOnly, + [switch]$Help +) + +$ErrorActionPreference = 'Stop' + +# Show help if requested +if ($Help) { + Write-Output @" +Usage: check-prerequisites.ps1 [OPTIONS] + +Consolidated prerequisite checking for Spec-Driven Development workflow. + +OPTIONS: + -Json Output in JSON format + -RequireTasks Require tasks.md to exist (for implementation phase) + -IncludeTasks Include tasks.md in AVAILABLE_DOCS list + -PathsOnly Only output path variables (no prerequisite validation) + -Help, -h Show this help message + +EXAMPLES: + # Check task prerequisites (plan.md required) + .\check-prerequisites.ps1 -Json + + # Check implementation prerequisites (plan.md + tasks.md required) + .\check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks + + # Get feature paths only (no validation) + .\check-prerequisites.ps1 -PathsOnly + +"@ + exit 0 +} + +# Source common functions +. "$PSScriptRoot/common.ps1" + +# Get feature paths and validate branch +$paths = Get-FeaturePathsEnv + +if (-not (Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit:$paths.HAS_GIT)) { + exit 1 +} + +# If paths-only mode, output paths and exit (support combined -Json -PathsOnly) +if ($PathsOnly) { + if ($Json) { + [PSCustomObject]@{ + REPO_ROOT = $paths.REPO_ROOT + BRANCH = $paths.CURRENT_BRANCH + FEATURE_DIR = $paths.FEATURE_DIR + FEATURE_SPEC = $paths.FEATURE_SPEC + IMPL_PLAN = $paths.IMPL_PLAN + TASKS = $paths.TASKS + } | ConvertTo-Json -Compress + } + else { + Write-Output "REPO_ROOT: $($paths.REPO_ROOT)" + Write-Output "BRANCH: $($paths.CURRENT_BRANCH)" + Write-Output "FEATURE_DIR: $($paths.FEATURE_DIR)" + Write-Output "FEATURE_SPEC: $($paths.FEATURE_SPEC)" + Write-Output "IMPL_PLAN: $($paths.IMPL_PLAN)" + Write-Output "TASKS: $($paths.TASKS)" + } + exit 0 +} + +# Validate required directories and files +if (-not (Test-Path $paths.FEATURE_DIR -PathType Container)) { + Write-Output "ERROR: Feature directory not found: $($paths.FEATURE_DIR)" + Write-Output "Run /speckit.specify first to create the feature structure." + exit 1 +} + +if (-not (Test-Path $paths.IMPL_PLAN -PathType Leaf)) { + Write-Output "ERROR: plan.md not found in $($paths.FEATURE_DIR)" + Write-Output "Run /speckit.plan first to create the implementation plan." + exit 1 +} + +# Check for tasks.md if required +if ($RequireTasks -and -not (Test-Path $paths.TASKS -PathType Leaf)) { + Write-Output "ERROR: tasks.md not found in $($paths.FEATURE_DIR)" + Write-Output "Run /speckit.tasks first to create the task list." + exit 1 +} + +# Build list of available documents +$docs = @() + +# Always check these optional docs +if (Test-Path $paths.RESEARCH) { $docs += 'research.md' } +if (Test-Path $paths.DATA_MODEL) { $docs += 'data-model.md' } + +# Check contracts directory (only if it exists and has files) +if ((Test-Path $paths.CONTRACTS_DIR) -and (Get-ChildItem -Path $paths.CONTRACTS_DIR -ErrorAction SilentlyContinue | Select-Object -First 1)) { + $docs += 'contracts/' +} + +if (Test-Path $paths.QUICKSTART) { $docs += 'quickstart.md' } + +# Include tasks.md if requested and it exists +if ($IncludeTasks -and (Test-Path $paths.TASKS)) { + $docs += 'tasks.md' +} + +# Output results +if ($Json) { + # JSON output + [PSCustomObject]@{ + FEATURE_DIR = $paths.FEATURE_DIR + AVAILABLE_DOCS = $docs + } | ConvertTo-Json -Compress +} +else { + # Text output + Write-Output "FEATURE_DIR:$($paths.FEATURE_DIR)" + Write-Output "AVAILABLE_DOCS:" + + # Show status of each potential document + Test-FileExists -Path $paths.RESEARCH -Description 'research.md' | Out-Null + Test-FileExists -Path $paths.DATA_MODEL -Description 'data-model.md' | Out-Null + Test-DirHasFiles -Path $paths.CONTRACTS_DIR -Description 'contracts/' | Out-Null + Test-FileExists -Path $paths.QUICKSTART -Description 'quickstart.md' | Out-Null + + if ($IncludeTasks) { + Test-FileExists -Path $paths.TASKS -Description 'tasks.md' | Out-Null + } +} diff --git a/.specify/scripts/powershell/common.ps1 b/.specify/scripts/powershell/common.ps1 new file mode 100644 index 00000000..a2b96cb1 --- /dev/null +++ b/.specify/scripts/powershell/common.ps1 @@ -0,0 +1,142 @@ +#!/usr/bin/env pwsh +# Common PowerShell functions analogous to common.sh + +function Get-RepoRoot { + try { + $result = git rev-parse --show-toplevel 2>$null + if ($LASTEXITCODE -eq 0) { + return $result + } + } + catch { + # Git command failed + } + + # Fall back to script location for non-git repos + return (Resolve-Path (Join-Path $PSScriptRoot "../../..")).Path +} + +function Get-CurrentBranch { + # First check if SPECIFY_FEATURE environment variable is set + if ($env:SPECIFY_FEATURE) { + return $env:SPECIFY_FEATURE + } + + # Then check git if available + try { + $result = git rev-parse --abbrev-ref HEAD 2>$null + if ($LASTEXITCODE -eq 0) { + return $result + } + } + catch { + # Git command failed + } + + # For non-git repos, try to find the latest feature directory + $repoRoot = Get-RepoRoot + $specsDir = Join-Path $repoRoot "specs" + + if (Test-Path $specsDir) { + $latestFeature = "" + $highest = 0 + + Get-ChildItem -Path $specsDir -Directory | ForEach-Object { + if ($_.Name -match '^(\d{3})-') { + $num = [int]$matches[1] + if ($num -gt $highest) { + $highest = $num + $latestFeature = $_.Name + } + } + } + + if ($latestFeature) { + return $latestFeature + } + } + + # Final fallback + return "main" +} + +function Test-HasGit { + try { + git rev-parse --show-toplevel 2>$null | Out-Null + return ($LASTEXITCODE -eq 0) + } + catch { + return $false + } +} + +function Test-FeatureBranch { + param( + [string]$Branch, + [bool]$HasGit = $true + ) + + # For non-git repos, we can't enforce branch naming but still provide output + if (-not $HasGit) { + Write-Warning "[specify] Warning: Git repository not detected; skipped branch validation" + return $true + } + + if ($Branch -notmatch '^[0-9]{3}-') { + Write-Output "ERROR: Not on a feature branch. Current branch: $Branch" + Write-Output "Feature branches should be named like: 001-feature-name" + return $false + } + return $true +} + +function Get-FeatureDir { + param([string]$RepoRoot, [string]$Branch) + Join-Path $RepoRoot "specs/$Branch" +} + +function Get-FeaturePathsEnv { + $repoRoot = Get-RepoRoot + $currentBranch = Get-CurrentBranch + $hasGit = Test-HasGit + $featureDir = Get-FeatureDir -RepoRoot $repoRoot -Branch $currentBranch + + [PSCustomObject]@{ + REPO_ROOT = $repoRoot + CURRENT_BRANCH = $currentBranch + HAS_GIT = $hasGit + FEATURE_DIR = $featureDir + FEATURE_SPEC = Join-Path $featureDir 'spec.md' + IMPL_PLAN = Join-Path $featureDir 'plan.md' + TASKS = Join-Path $featureDir 'tasks.md' + RESEARCH = Join-Path $featureDir 'research.md' + DATA_MODEL = Join-Path $featureDir 'data-model.md' + QUICKSTART = Join-Path $featureDir 'quickstart.md' + CONTRACTS_DIR = Join-Path $featureDir 'contracts' + } +} + +function Test-FileExists { + param([string]$Path, [string]$Description) + if (Test-Path -Path $Path -PathType Leaf) { + Write-Output " ✓ $Description" + return $true + } + else { + Write-Output " ✗ $Description" + return $false + } +} + +function Test-DirHasFiles { + param([string]$Path, [string]$Description) + if ((Test-Path -Path $Path -PathType Container) -and (Get-ChildItem -Path $Path -ErrorAction SilentlyContinue | Where-Object { -not $_.PSIsContainer } | Select-Object -First 1)) { + Write-Output " ✓ $Description" + return $true + } + else { + Write-Output " ✗ $Description" + return $false + } +} + diff --git a/.specify/scripts/powershell/create-new-feature.ps1 b/.specify/scripts/powershell/create-new-feature.ps1 new file mode 100644 index 00000000..4daa6d2c --- /dev/null +++ b/.specify/scripts/powershell/create-new-feature.ps1 @@ -0,0 +1,290 @@ +#!/usr/bin/env pwsh +# Create a new feature +[CmdletBinding()] +param( + [switch]$Json, + [string]$ShortName, + [int]$Number = 0, + [switch]$Help, + [Parameter(ValueFromRemainingArguments = $true)] + [string[]]$FeatureDescription +) +$ErrorActionPreference = 'Stop' + +# Show help if requested +if ($Help) { + Write-Host "Usage: ./create-new-feature.ps1 [-Json] [-ShortName ] [-Number N] " + Write-Host "" + Write-Host "Options:" + Write-Host " -Json Output in JSON format" + Write-Host " -ShortName Provide a custom short name (2-4 words) for the branch" + Write-Host " -Number N Specify branch number manually (overrides auto-detection)" + Write-Host " -Help Show this help message" + Write-Host "" + Write-Host "Examples:" + Write-Host " ./create-new-feature.ps1 'Add user authentication system' -ShortName 'user-auth'" + Write-Host " ./create-new-feature.ps1 'Implement OAuth2 integration for API'" + exit 0 +} + +# Check if feature description provided +if (-not $FeatureDescription -or $FeatureDescription.Count -eq 0) { + Write-Error "Usage: ./create-new-feature.ps1 [-Json] [-ShortName ] " + exit 1 +} + +$featureDesc = ($FeatureDescription -join ' ').Trim() + +# Resolve repository root. Prefer git information when available, but fall back +# to searching for repository markers so the workflow still functions in repositories that +# were initialized with --no-git. +function Find-RepositoryRoot { + param( + [string]$StartDir, + [string[]]$Markers = @('.git', '.specify') + ) + $current = Resolve-Path $StartDir + while ($true) { + foreach ($marker in $Markers) { + if (Test-Path (Join-Path $current $marker)) { + return $current + } + } + $parent = Split-Path $current -Parent + if ($parent -eq $current) { + # Reached filesystem root without finding markers + return $null + } + $current = $parent + } +} + +function Get-NextBranchNumber { + param( + [string]$ShortName, + [string]$SpecsDir + ) + + # Fetch all remotes to get latest branch info (suppress errors if no remotes) + try { + git fetch --all --prune 2>$null | Out-Null + } catch { + # Ignore fetch errors + } + + # Find remote branches matching the pattern using git ls-remote + $remoteBranches = @() + try { + $remoteRefs = git ls-remote --heads origin 2>$null + if ($remoteRefs) { + $remoteBranches = $remoteRefs | Where-Object { $_ -match "refs/heads/(\d+)-$([regex]::Escape($ShortName))$" } | ForEach-Object { + if ($_ -match "refs/heads/(\d+)-") { + [int]$matches[1] + } + } + } + } catch { + # Ignore errors + } + + # Check local branches + $localBranches = @() + try { + $allBranches = git branch 2>$null + if ($allBranches) { + $localBranches = $allBranches | Where-Object { $_ -match "^\*?\s*(\d+)-$([regex]::Escape($ShortName))$" } | ForEach-Object { + if ($_ -match "(\d+)-") { + [int]$matches[1] + } + } + } + } catch { + # Ignore errors + } + + # Check specs directory + $specDirs = @() + if (Test-Path $SpecsDir) { + try { + $specDirs = Get-ChildItem -Path $SpecsDir -Directory | Where-Object { $_.Name -match "^(\d+)-$([regex]::Escape($ShortName))$" } | ForEach-Object { + if ($_.Name -match "^(\d+)-") { + [int]$matches[1] + } + } + } catch { + # Ignore errors + } + } + + # Combine all sources and get the highest number + $maxNum = 0 + foreach ($num in ($remoteBranches + $localBranches + $specDirs)) { + if ($num -gt $maxNum) { + $maxNum = $num + } + } + + # Return next number + return $maxNum + 1 +} +$fallbackRoot = (Find-RepositoryRoot -StartDir $PSScriptRoot) +if (-not $fallbackRoot) { + Write-Error "Error: Could not determine repository root. Please run this script from within the repository." + exit 1 +} + +try { + $repoRoot = git rev-parse --show-toplevel 2>$null + if ($LASTEXITCODE -eq 0) { + $hasGit = $true + } else { + throw "Git not available" + } +} catch { + $repoRoot = $fallbackRoot + $hasGit = $false +} + +Set-Location $repoRoot + +$specsDir = Join-Path $repoRoot 'specs' +New-Item -ItemType Directory -Path $specsDir -Force | Out-Null + +# Function to generate branch name with stop word filtering and length filtering +function Get-BranchName { + param([string]$Description) + + # Common stop words to filter out + $stopWords = @( + 'i', 'a', 'an', 'the', 'to', 'for', 'of', 'in', 'on', 'at', 'by', 'with', 'from', + 'is', 'are', 'was', 'were', 'be', 'been', 'being', 'have', 'has', 'had', + 'do', 'does', 'did', 'will', 'would', 'should', 'could', 'can', 'may', 'might', 'must', 'shall', + 'this', 'that', 'these', 'those', 'my', 'your', 'our', 'their', + 'want', 'need', 'add', 'get', 'set' + ) + + # Convert to lowercase and extract words (alphanumeric only) + $cleanName = $Description.ToLower() -replace '[^a-z0-9\s]', ' ' + $words = $cleanName -split '\s+' | Where-Object { $_ } + + # Filter words: remove stop words and words shorter than 3 chars (unless they're uppercase acronyms in original) + $meaningfulWords = @() + foreach ($word in $words) { + # Skip stop words + if ($stopWords -contains $word) { continue } + + # Keep words that are length >= 3 OR appear as uppercase in original (likely acronyms) + if ($word.Length -ge 3) { + $meaningfulWords += $word + } elseif ($Description -match "\b$($word.ToUpper())\b") { + # Keep short words if they appear as uppercase in original (likely acronyms) + $meaningfulWords += $word + } + } + + # If we have meaningful words, use first 3-4 of them + if ($meaningfulWords.Count -gt 0) { + $maxWords = if ($meaningfulWords.Count -eq 4) { 4 } else { 3 } + $result = ($meaningfulWords | Select-Object -First $maxWords) -join '-' + return $result + } else { + # Fallback to original logic if no meaningful words found + $result = $Description.ToLower() -replace '[^a-z0-9]', '-' -replace '-{2,}', '-' -replace '^-', '' -replace '-$', '' + $fallbackWords = ($result -split '-') | Where-Object { $_ } | Select-Object -First 3 + return [string]::Join('-', $fallbackWords) + } +} + +# Generate branch name +if ($ShortName) { + # Use provided short name, just clean it up + $branchSuffix = $ShortName.ToLower() -replace '[^a-z0-9]', '-' -replace '-{2,}', '-' -replace '^-', '' -replace '-$', '' +} else { + # Generate from description with smart filtering + $branchSuffix = Get-BranchName -Description $featureDesc +} + +# Determine branch number +if ($Number -eq 0) { + if ($hasGit) { + # Check existing branches on remotes + $Number = Get-NextBranchNumber -ShortName $branchSuffix -SpecsDir $specsDir + } else { + # Fall back to local directory check + $highest = 0 + if (Test-Path $specsDir) { + Get-ChildItem -Path $specsDir -Directory | ForEach-Object { + if ($_.Name -match '^(\d{3})') { + $num = [int]$matches[1] + if ($num -gt $highest) { $highest = $num } + } + } + } + $Number = $highest + 1 + } +} + +$featureNum = ('{0:000}' -f $Number) +$branchName = "$featureNum-$branchSuffix" + +# GitHub enforces a 244-byte limit on branch names +# Validate and truncate if necessary +$maxBranchLength = 244 +if ($branchName.Length -gt $maxBranchLength) { + # Calculate how much we need to trim from suffix + # Account for: feature number (3) + hyphen (1) = 4 chars + $maxSuffixLength = $maxBranchLength - 4 + + # Truncate suffix + $truncatedSuffix = $branchSuffix.Substring(0, [Math]::Min($branchSuffix.Length, $maxSuffixLength)) + # Remove trailing hyphen if truncation created one + $truncatedSuffix = $truncatedSuffix -replace '-$', '' + + $originalBranchName = $branchName + $branchName = "$featureNum-$truncatedSuffix" + + Write-Warning "[specify] Branch name exceeded GitHub's 244-byte limit" + Write-Warning "[specify] Original: $originalBranchName ($($originalBranchName.Length) bytes)" + Write-Warning "[specify] Truncated to: $branchName ($($branchName.Length) bytes)" +} + +if ($hasGit) { + try { + git checkout -b $branchName | Out-Null + } catch { + Write-Warning "Failed to create git branch: $branchName" + } +} else { + Write-Warning "[specify] Warning: Git repository not detected; skipped branch creation for $branchName" +} + +$featureDir = Join-Path $specsDir $branchName +New-Item -ItemType Directory -Path $featureDir -Force | Out-Null + +$template = Join-Path $repoRoot '.specify/templates/spec-template.md' +$specFile = Join-Path $featureDir 'spec.md' +if (Test-Path $template) { + Copy-Item $template $specFile -Force +} else { + New-Item -ItemType File -Path $specFile | Out-Null +} + +# Set the SPECIFY_FEATURE environment variable for the current session +$env:SPECIFY_FEATURE = $branchName + +if ($Json) { + $obj = [PSCustomObject]@{ + BRANCH_NAME = $branchName + SPEC_FILE = $specFile + FEATURE_NUM = $featureNum + HAS_GIT = $hasGit + } + $obj | ConvertTo-Json -Compress +} else { + Write-Output "BRANCH_NAME: $branchName" + Write-Output "SPEC_FILE: $specFile" + Write-Output "FEATURE_NUM: $featureNum" + Write-Output "HAS_GIT: $hasGit" + Write-Output "SPECIFY_FEATURE environment variable set to: $branchName" +} + diff --git a/.specify/scripts/powershell/setup-plan.ps1 b/.specify/scripts/powershell/setup-plan.ps1 new file mode 100644 index 00000000..93d19938 --- /dev/null +++ b/.specify/scripts/powershell/setup-plan.ps1 @@ -0,0 +1,64 @@ +#!/usr/bin/env pwsh +# Setup implementation plan for a feature + +[CmdletBinding()] +param( + [switch]$Json, + [switch]$Help +) + +$ErrorActionPreference = 'Stop' + +# Show help if requested +if ($Help) { + Write-Output "Usage: ./setup-plan.ps1 [-Json] [-Help]" + Write-Output " -Json Output results in JSON format" + Write-Output " -Help Show this help message" + exit 0 +} + +# Load common functions +. "$PSScriptRoot/common.ps1" + +# Get all paths and variables from common functions +$paths = Get-FeaturePathsEnv + +# Check if we're on a proper feature branch (only for git repos) +if (-not (Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit $paths.HAS_GIT)) { + exit 1 +} + +# Ensure the feature directory exists +New-Item -ItemType Directory -Path $paths.FEATURE_DIR -Force | Out-Null + +# Copy plan template if it exists, otherwise note it or create empty file +$template = Join-Path $paths.REPO_ROOT '.specify/templates/plan-template.md' +if (Test-Path $template) { + Copy-Item $template $paths.IMPL_PLAN -Force + Write-Output "Copied plan template to $($paths.IMPL_PLAN)" +} +else { + Write-Warning "Plan template not found at $template" + # Create a basic plan file if template doesn't exist + New-Item -ItemType File -Path $paths.IMPL_PLAN -Force | Out-Null +} + +# Output results +if ($Json) { + $result = [PSCustomObject]@{ + FEATURE_SPEC = $paths.FEATURE_SPEC + IMPL_PLAN = $paths.IMPL_PLAN + SPECS_DIR = $paths.FEATURE_DIR + BRANCH = $paths.CURRENT_BRANCH + HAS_GIT = $paths.HAS_GIT + } + $result | ConvertTo-Json -Compress +} +else { + Write-Output "FEATURE_SPEC: $($paths.FEATURE_SPEC)" + Write-Output "IMPL_PLAN: $($paths.IMPL_PLAN)" + Write-Output "SPECS_DIR: $($paths.FEATURE_DIR)" + Write-Output "BRANCH: $($paths.CURRENT_BRANCH)" + Write-Output "HAS_GIT: $($paths.HAS_GIT)" +} + diff --git a/.specify/scripts/powershell/update-agent-context.ps1 b/.specify/scripts/powershell/update-agent-context.ps1 new file mode 100644 index 00000000..695e28b8 --- /dev/null +++ b/.specify/scripts/powershell/update-agent-context.ps1 @@ -0,0 +1,439 @@ +#!/usr/bin/env pwsh +<#! +.SYNOPSIS +Update agent context files with information from plan.md (PowerShell version) + +.DESCRIPTION +Mirrors the behavior of scripts/bash/update-agent-context.sh: + 1. Environment Validation + 2. Plan Data Extraction + 3. Agent File Management (create from template or update existing) + 4. Content Generation (technology stack, recent changes, timestamp) + 5. Multi-Agent Support (claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, roo, amp, q) + +.PARAMETER AgentType +Optional agent key to update a single agent. If omitted, updates all existing agent files (creating a default Claude file if none exist). + +.EXAMPLE +./update-agent-context.ps1 -AgentType claude + +.EXAMPLE +./update-agent-context.ps1 # Updates all existing agent files + +.NOTES +Relies on common helper functions in common.ps1 +#> +param( + [Parameter(Position=0)] + [ValidateSet('claude','gemini','copilot','cursor-agent','qwen','opencode','codex','windsurf','kilocode','auggie','roo','codebuddy','amp','q')] + [string]$AgentType +) + +$ErrorActionPreference = 'Stop' + +# Import common helpers +$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path +. (Join-Path $ScriptDir 'common.ps1') + +# Acquire environment paths +$envData = Get-FeaturePathsEnv +$REPO_ROOT = $envData.REPO_ROOT +$CURRENT_BRANCH = $envData.CURRENT_BRANCH +$HAS_GIT = $envData.HAS_GIT +$IMPL_PLAN = $envData.IMPL_PLAN +$NEW_PLAN = $IMPL_PLAN + +# Agent file paths +$CLAUDE_FILE = Join-Path $REPO_ROOT 'CLAUDE.md' +$GEMINI_FILE = Join-Path $REPO_ROOT 'GEMINI.md' +$COPILOT_FILE = Join-Path $REPO_ROOT '.github/copilot-instructions.md' +$CURSOR_FILE = Join-Path $REPO_ROOT '.cursor/rules/specify-rules.mdc' +$QWEN_FILE = Join-Path $REPO_ROOT 'QWEN.md' +$AGENTS_FILE = Join-Path $REPO_ROOT 'AGENTS.md' +$WINDSURF_FILE = Join-Path $REPO_ROOT '.windsurf/rules/specify-rules.md' +$KILOCODE_FILE = Join-Path $REPO_ROOT '.kilocode/rules/specify-rules.md' +$AUGGIE_FILE = Join-Path $REPO_ROOT '.augment/rules/specify-rules.md' +$ROO_FILE = Join-Path $REPO_ROOT '.roo/rules/specify-rules.md' +$CODEBUDDY_FILE = Join-Path $REPO_ROOT 'CODEBUDDY.md' +$AMP_FILE = Join-Path $REPO_ROOT 'AGENTS.md' +$Q_FILE = Join-Path $REPO_ROOT 'AGENTS.md' + +$TEMPLATE_FILE = Join-Path $REPO_ROOT '.specify/templates/agent-file-template.md' + +# Parsed plan data placeholders +$script:NEW_LANG = '' +$script:NEW_FRAMEWORK = '' +$script:NEW_DB = '' +$script:NEW_PROJECT_TYPE = '' + +function Write-Info { + param( + [Parameter(Mandatory=$true)] + [string]$Message + ) + Write-Host "INFO: $Message" +} + +function Write-Success { + param( + [Parameter(Mandatory=$true)] + [string]$Message + ) + Write-Host "$([char]0x2713) $Message" +} + +function Write-WarningMsg { + param( + [Parameter(Mandatory=$true)] + [string]$Message + ) + Write-Warning $Message +} + +function Write-Err { + param( + [Parameter(Mandatory=$true)] + [string]$Message + ) + Write-Host "ERROR: $Message" -ForegroundColor Red +} + +function Validate-Environment { + if (-not $CURRENT_BRANCH) { + Write-Err 'Unable to determine current feature' + if ($HAS_GIT) { Write-Info "Make sure you're on a feature branch" } else { Write-Info 'Set SPECIFY_FEATURE environment variable or create a feature first' } + exit 1 + } + if (-not (Test-Path $NEW_PLAN)) { + Write-Err "No plan.md found at $NEW_PLAN" + Write-Info 'Ensure you are working on a feature with a corresponding spec directory' + if (-not $HAS_GIT) { Write-Info 'Use: $env:SPECIFY_FEATURE=your-feature-name or create a new feature first' } + exit 1 + } + if (-not (Test-Path $TEMPLATE_FILE)) { + Write-Err "Template file not found at $TEMPLATE_FILE" + Write-Info 'Run specify init to scaffold .specify/templates, or add agent-file-template.md there.' + exit 1 + } +} + +function Extract-PlanField { + param( + [Parameter(Mandatory=$true)] + [string]$FieldPattern, + [Parameter(Mandatory=$true)] + [string]$PlanFile + ) + if (-not (Test-Path $PlanFile)) { return '' } + # Lines like **Language/Version**: Python 3.12 + $regex = "^\*\*$([Regex]::Escape($FieldPattern))\*\*: (.+)$" + Get-Content -LiteralPath $PlanFile -Encoding utf8 | ForEach-Object { + if ($_ -match $regex) { + $val = $Matches[1].Trim() + if ($val -notin @('NEEDS CLARIFICATION','N/A')) { return $val } + } + } | Select-Object -First 1 +} + +function Parse-PlanData { + param( + [Parameter(Mandatory=$true)] + [string]$PlanFile + ) + if (-not (Test-Path $PlanFile)) { Write-Err "Plan file not found: $PlanFile"; return $false } + Write-Info "Parsing plan data from $PlanFile" + $script:NEW_LANG = Extract-PlanField -FieldPattern 'Language/Version' -PlanFile $PlanFile + $script:NEW_FRAMEWORK = Extract-PlanField -FieldPattern 'Primary Dependencies' -PlanFile $PlanFile + $script:NEW_DB = Extract-PlanField -FieldPattern 'Storage' -PlanFile $PlanFile + $script:NEW_PROJECT_TYPE = Extract-PlanField -FieldPattern 'Project Type' -PlanFile $PlanFile + + if ($NEW_LANG) { Write-Info "Found language: $NEW_LANG" } else { Write-WarningMsg 'No language information found in plan' } + if ($NEW_FRAMEWORK) { Write-Info "Found framework: $NEW_FRAMEWORK" } + if ($NEW_DB -and $NEW_DB -ne 'N/A') { Write-Info "Found database: $NEW_DB" } + if ($NEW_PROJECT_TYPE) { Write-Info "Found project type: $NEW_PROJECT_TYPE" } + return $true +} + +function Format-TechnologyStack { + param( + [Parameter(Mandatory=$false)] + [string]$Lang, + [Parameter(Mandatory=$false)] + [string]$Framework + ) + $parts = @() + if ($Lang -and $Lang -ne 'NEEDS CLARIFICATION') { $parts += $Lang } + if ($Framework -and $Framework -notin @('NEEDS CLARIFICATION','N/A')) { $parts += $Framework } + if (-not $parts) { return '' } + return ($parts -join ' + ') +} + +function Get-ProjectStructure { + param( + [Parameter(Mandatory=$false)] + [string]$ProjectType + ) + if ($ProjectType -match 'web') { return "backend/`nfrontend/`ntests/" } else { return "src/`ntests/" } +} + +function Get-CommandsForLanguage { + param( + [Parameter(Mandatory=$false)] + [string]$Lang + ) + switch -Regex ($Lang) { + 'Python' { return "cd src; pytest; ruff check ." } + 'Rust' { return "cargo test; cargo clippy" } + 'JavaScript|TypeScript' { return "npm test; npm run lint" } + default { return "# Add commands for $Lang" } + } +} + +function Get-LanguageConventions { + param( + [Parameter(Mandatory=$false)] + [string]$Lang + ) + if ($Lang) { "${Lang}: Follow standard conventions" } else { 'General: Follow standard conventions' } +} + +function New-AgentFile { + param( + [Parameter(Mandatory=$true)] + [string]$TargetFile, + [Parameter(Mandatory=$true)] + [string]$ProjectName, + [Parameter(Mandatory=$true)] + [datetime]$Date + ) + if (-not (Test-Path $TEMPLATE_FILE)) { Write-Err "Template not found at $TEMPLATE_FILE"; return $false } + $temp = New-TemporaryFile + Copy-Item -LiteralPath $TEMPLATE_FILE -Destination $temp -Force + + $projectStructure = Get-ProjectStructure -ProjectType $NEW_PROJECT_TYPE + $commands = Get-CommandsForLanguage -Lang $NEW_LANG + $languageConventions = Get-LanguageConventions -Lang $NEW_LANG + + $escaped_lang = $NEW_LANG + $escaped_framework = $NEW_FRAMEWORK + $escaped_branch = $CURRENT_BRANCH + + $content = Get-Content -LiteralPath $temp -Raw -Encoding utf8 + $content = $content -replace '\[PROJECT NAME\]',$ProjectName + $content = $content -replace '\[DATE\]',$Date.ToString('yyyy-MM-dd') + + # Build the technology stack string safely + $techStackForTemplate = "" + if ($escaped_lang -and $escaped_framework) { + $techStackForTemplate = "- $escaped_lang + $escaped_framework ($escaped_branch)" + } elseif ($escaped_lang) { + $techStackForTemplate = "- $escaped_lang ($escaped_branch)" + } elseif ($escaped_framework) { + $techStackForTemplate = "- $escaped_framework ($escaped_branch)" + } + + $content = $content -replace '\[EXTRACTED FROM ALL PLAN.MD FILES\]',$techStackForTemplate + # For project structure we manually embed (keep newlines) + $escapedStructure = [Regex]::Escape($projectStructure) + $content = $content -replace '\[ACTUAL STRUCTURE FROM PLANS\]',$escapedStructure + # Replace escaped newlines placeholder after all replacements + $content = $content -replace '\[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES\]',$commands + $content = $content -replace '\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]',$languageConventions + + # Build the recent changes string safely + $recentChangesForTemplate = "" + if ($escaped_lang -and $escaped_framework) { + $recentChangesForTemplate = "- ${escaped_branch}: Added ${escaped_lang} + ${escaped_framework}" + } elseif ($escaped_lang) { + $recentChangesForTemplate = "- ${escaped_branch}: Added ${escaped_lang}" + } elseif ($escaped_framework) { + $recentChangesForTemplate = "- ${escaped_branch}: Added ${escaped_framework}" + } + + $content = $content -replace '\[LAST 3 FEATURES AND WHAT THEY ADDED\]',$recentChangesForTemplate + # Convert literal \n sequences introduced by Escape to real newlines + $content = $content -replace '\\n',[Environment]::NewLine + + $parent = Split-Path -Parent $TargetFile + if (-not (Test-Path $parent)) { New-Item -ItemType Directory -Path $parent | Out-Null } + Set-Content -LiteralPath $TargetFile -Value $content -NoNewline -Encoding utf8 + Remove-Item $temp -Force + return $true +} + +function Update-ExistingAgentFile { + param( + [Parameter(Mandatory=$true)] + [string]$TargetFile, + [Parameter(Mandatory=$true)] + [datetime]$Date + ) + if (-not (Test-Path $TargetFile)) { return (New-AgentFile -TargetFile $TargetFile -ProjectName (Split-Path $REPO_ROOT -Leaf) -Date $Date) } + + $techStack = Format-TechnologyStack -Lang $NEW_LANG -Framework $NEW_FRAMEWORK + $newTechEntries = @() + if ($techStack) { + $escapedTechStack = [Regex]::Escape($techStack) + if (-not (Select-String -Pattern $escapedTechStack -Path $TargetFile -Quiet)) { + $newTechEntries += "- $techStack ($CURRENT_BRANCH)" + } + } + if ($NEW_DB -and $NEW_DB -notin @('N/A','NEEDS CLARIFICATION')) { + $escapedDB = [Regex]::Escape($NEW_DB) + if (-not (Select-String -Pattern $escapedDB -Path $TargetFile -Quiet)) { + $newTechEntries += "- $NEW_DB ($CURRENT_BRANCH)" + } + } + $newChangeEntry = '' + if ($techStack) { $newChangeEntry = "- ${CURRENT_BRANCH}: Added ${techStack}" } + elseif ($NEW_DB -and $NEW_DB -notin @('N/A','NEEDS CLARIFICATION')) { $newChangeEntry = "- ${CURRENT_BRANCH}: Added ${NEW_DB}" } + + $lines = Get-Content -LiteralPath $TargetFile -Encoding utf8 + $output = New-Object System.Collections.Generic.List[string] + $inTech = $false; $inChanges = $false; $techAdded = $false; $changeAdded = $false; $existingChanges = 0 + + for ($i=0; $i -lt $lines.Count; $i++) { + $line = $lines[$i] + if ($line -eq '## Active Technologies') { + $output.Add($line) + $inTech = $true + continue + } + if ($inTech -and $line -match '^##\s') { + if (-not $techAdded -and $newTechEntries.Count -gt 0) { $newTechEntries | ForEach-Object { $output.Add($_) }; $techAdded = $true } + $output.Add($line); $inTech = $false; continue + } + if ($inTech -and [string]::IsNullOrWhiteSpace($line)) { + if (-not $techAdded -and $newTechEntries.Count -gt 0) { $newTechEntries | ForEach-Object { $output.Add($_) }; $techAdded = $true } + $output.Add($line); continue + } + if ($line -eq '## Recent Changes') { + $output.Add($line) + if ($newChangeEntry) { $output.Add($newChangeEntry); $changeAdded = $true } + $inChanges = $true + continue + } + if ($inChanges -and $line -match '^##\s') { $output.Add($line); $inChanges = $false; continue } + if ($inChanges -and $line -match '^- ') { + if ($existingChanges -lt 2) { $output.Add($line); $existingChanges++ } + continue + } + if ($line -match '\*\*Last updated\*\*: .*\d{4}-\d{2}-\d{2}') { + $output.Add(($line -replace '\d{4}-\d{2}-\d{2}',$Date.ToString('yyyy-MM-dd'))) + continue + } + $output.Add($line) + } + + # Post-loop check: if we're still in the Active Technologies section and haven't added new entries + if ($inTech -and -not $techAdded -and $newTechEntries.Count -gt 0) { + $newTechEntries | ForEach-Object { $output.Add($_) } + } + + Set-Content -LiteralPath $TargetFile -Value ($output -join [Environment]::NewLine) -Encoding utf8 + return $true +} + +function Update-AgentFile { + param( + [Parameter(Mandatory=$true)] + [string]$TargetFile, + [Parameter(Mandatory=$true)] + [string]$AgentName + ) + if (-not $TargetFile -or -not $AgentName) { Write-Err 'Update-AgentFile requires TargetFile and AgentName'; return $false } + Write-Info "Updating $AgentName context file: $TargetFile" + $projectName = Split-Path $REPO_ROOT -Leaf + $date = Get-Date + + $dir = Split-Path -Parent $TargetFile + if (-not (Test-Path $dir)) { New-Item -ItemType Directory -Path $dir | Out-Null } + + if (-not (Test-Path $TargetFile)) { + if (New-AgentFile -TargetFile $TargetFile -ProjectName $projectName -Date $date) { Write-Success "Created new $AgentName context file" } else { Write-Err 'Failed to create new agent file'; return $false } + } else { + try { + if (Update-ExistingAgentFile -TargetFile $TargetFile -Date $date) { Write-Success "Updated existing $AgentName context file" } else { Write-Err 'Failed to update agent file'; return $false } + } catch { + Write-Err "Cannot access or update existing file: $TargetFile. $_" + return $false + } + } + return $true +} + +function Update-SpecificAgent { + param( + [Parameter(Mandatory=$true)] + [string]$Type + ) + switch ($Type) { + 'claude' { Update-AgentFile -TargetFile $CLAUDE_FILE -AgentName 'Claude Code' } + 'gemini' { Update-AgentFile -TargetFile $GEMINI_FILE -AgentName 'Gemini CLI' } + 'copilot' { Update-AgentFile -TargetFile $COPILOT_FILE -AgentName 'GitHub Copilot' } + 'cursor-agent' { Update-AgentFile -TargetFile $CURSOR_FILE -AgentName 'Cursor IDE' } + 'qwen' { Update-AgentFile -TargetFile $QWEN_FILE -AgentName 'Qwen Code' } + 'opencode' { Update-AgentFile -TargetFile $AGENTS_FILE -AgentName 'opencode' } + 'codex' { Update-AgentFile -TargetFile $AGENTS_FILE -AgentName 'Codex CLI' } + 'windsurf' { Update-AgentFile -TargetFile $WINDSURF_FILE -AgentName 'Windsurf' } + 'kilocode' { Update-AgentFile -TargetFile $KILOCODE_FILE -AgentName 'Kilo Code' } + 'auggie' { Update-AgentFile -TargetFile $AUGGIE_FILE -AgentName 'Auggie CLI' } + 'roo' { Update-AgentFile -TargetFile $ROO_FILE -AgentName 'Roo Code' } + 'codebuddy' { Update-AgentFile -TargetFile $CODEBUDDY_FILE -AgentName 'CodeBuddy CLI' } + 'amp' { Update-AgentFile -TargetFile $AMP_FILE -AgentName 'Amp' } + 'q' { Update-AgentFile -TargetFile $Q_FILE -AgentName 'Amazon Q Developer CLI' } + default { Write-Err "Unknown agent type '$Type'"; Write-Err 'Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|q'; return $false } + } +} + +function Update-AllExistingAgents { + $found = $false + $ok = $true + if (Test-Path $CLAUDE_FILE) { if (-not (Update-AgentFile -TargetFile $CLAUDE_FILE -AgentName 'Claude Code')) { $ok = $false }; $found = $true } + if (Test-Path $GEMINI_FILE) { if (-not (Update-AgentFile -TargetFile $GEMINI_FILE -AgentName 'Gemini CLI')) { $ok = $false }; $found = $true } + if (Test-Path $COPILOT_FILE) { if (-not (Update-AgentFile -TargetFile $COPILOT_FILE -AgentName 'GitHub Copilot')) { $ok = $false }; $found = $true } + if (Test-Path $CURSOR_FILE) { if (-not (Update-AgentFile -TargetFile $CURSOR_FILE -AgentName 'Cursor IDE')) { $ok = $false }; $found = $true } + if (Test-Path $QWEN_FILE) { if (-not (Update-AgentFile -TargetFile $QWEN_FILE -AgentName 'Qwen Code')) { $ok = $false }; $found = $true } + if (Test-Path $AGENTS_FILE) { if (-not (Update-AgentFile -TargetFile $AGENTS_FILE -AgentName 'Codex/opencode')) { $ok = $false }; $found = $true } + if (Test-Path $WINDSURF_FILE) { if (-not (Update-AgentFile -TargetFile $WINDSURF_FILE -AgentName 'Windsurf')) { $ok = $false }; $found = $true } + if (Test-Path $KILOCODE_FILE) { if (-not (Update-AgentFile -TargetFile $KILOCODE_FILE -AgentName 'Kilo Code')) { $ok = $false }; $found = $true } + if (Test-Path $AUGGIE_FILE) { if (-not (Update-AgentFile -TargetFile $AUGGIE_FILE -AgentName 'Auggie CLI')) { $ok = $false }; $found = $true } + if (Test-Path $ROO_FILE) { if (-not (Update-AgentFile -TargetFile $ROO_FILE -AgentName 'Roo Code')) { $ok = $false }; $found = $true } + if (Test-Path $CODEBUDDY_FILE) { if (-not (Update-AgentFile -TargetFile $CODEBUDDY_FILE -AgentName 'CodeBuddy CLI')) { $ok = $false }; $found = $true } + if (Test-Path $Q_FILE) { if (-not (Update-AgentFile -TargetFile $Q_FILE -AgentName 'Amazon Q Developer CLI')) { $ok = $false }; $found = $true } + if (-not $found) { + Write-Info 'No existing agent files found, creating default Claude file...' + if (-not (Update-AgentFile -TargetFile $CLAUDE_FILE -AgentName 'Claude Code')) { $ok = $false } + } + return $ok +} + +function Print-Summary { + Write-Host '' + Write-Info 'Summary of changes:' + if ($NEW_LANG) { Write-Host " - Added language: $NEW_LANG" } + if ($NEW_FRAMEWORK) { Write-Host " - Added framework: $NEW_FRAMEWORK" } + if ($NEW_DB -and $NEW_DB -ne 'N/A') { Write-Host " - Added database: $NEW_DB" } + Write-Host '' + Write-Info 'Usage: ./update-agent-context.ps1 [-AgentType claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|q]' +} + +function Main { + Validate-Environment + Write-Info "=== Updating agent context files for feature $CURRENT_BRANCH ===" + if (-not (Parse-PlanData -PlanFile $NEW_PLAN)) { Write-Err 'Failed to parse plan data'; exit 1 } + $success = $true + if ($AgentType) { + Write-Info "Updating specific agent: $AgentType" + if (-not (Update-SpecificAgent -Type $AgentType)) { $success = $false } + } + else { + Write-Info 'No agent specified, updating all existing agent files...' + if (-not (Update-AllExistingAgents)) { $success = $false } + } + Print-Summary + if ($success) { Write-Success 'Agent context update completed successfully'; exit 0 } else { Write-Err 'Agent context update completed with errors'; exit 1 } +} + +Main + From 8e063e0edc553d0352abffe13e7c0090c7d66987 Mon Sep 17 00:00:00 2001 From: Dariusz Porowski <3431813+DariuszPorowski@users.noreply.github.com> Date: Thu, 6 Nov 2025 13:49:24 -0800 Subject: [PATCH 2/2] style(powershell): format Signed-off-by: Dariusz Porowski <3431813+DariuszPorowski@users.noreply.github.com> --- .../scripts/powershell/create-new-feature.ps1 | 46 +++-- .../powershell/update-agent-context.ps1 | 158 +++++++++--------- 2 files changed, 112 insertions(+), 92 deletions(-) diff --git a/.specify/scripts/powershell/create-new-feature.ps1 b/.specify/scripts/powershell/create-new-feature.ps1 index 4daa6d2c..53f23d32 100644 --- a/.specify/scripts/powershell/create-new-feature.ps1 +++ b/.specify/scripts/powershell/create-new-feature.ps1 @@ -68,7 +68,8 @@ function Get-NextBranchNumber { # Fetch all remotes to get latest branch info (suppress errors if no remotes) try { git fetch --all --prune 2>$null | Out-Null - } catch { + } + catch { # Ignore fetch errors } @@ -83,7 +84,8 @@ function Get-NextBranchNumber { } } } - } catch { + } + catch { # Ignore errors } @@ -98,7 +100,8 @@ function Get-NextBranchNumber { } } } - } catch { + } + catch { # Ignore errors } @@ -111,7 +114,8 @@ function Get-NextBranchNumber { [int]$matches[1] } } - } catch { + } + catch { # Ignore errors } } @@ -137,10 +141,12 @@ try { $repoRoot = git rev-parse --show-toplevel 2>$null if ($LASTEXITCODE -eq 0) { $hasGit = $true - } else { + } + else { throw "Git not available" } -} catch { +} +catch { $repoRoot = $fallbackRoot $hasGit = $false } @@ -176,7 +182,8 @@ function Get-BranchName { # Keep words that are length >= 3 OR appear as uppercase in original (likely acronyms) if ($word.Length -ge 3) { $meaningfulWords += $word - } elseif ($Description -match "\b$($word.ToUpper())\b") { + } + elseif ($Description -match "\b$($word.ToUpper())\b") { # Keep short words if they appear as uppercase in original (likely acronyms) $meaningfulWords += $word } @@ -187,7 +194,8 @@ function Get-BranchName { $maxWords = if ($meaningfulWords.Count -eq 4) { 4 } else { 3 } $result = ($meaningfulWords | Select-Object -First $maxWords) -join '-' return $result - } else { + } + else { # Fallback to original logic if no meaningful words found $result = $Description.ToLower() -replace '[^a-z0-9]', '-' -replace '-{2,}', '-' -replace '^-', '' -replace '-$', '' $fallbackWords = ($result -split '-') | Where-Object { $_ } | Select-Object -First 3 @@ -199,7 +207,8 @@ function Get-BranchName { if ($ShortName) { # Use provided short name, just clean it up $branchSuffix = $ShortName.ToLower() -replace '[^a-z0-9]', '-' -replace '-{2,}', '-' -replace '^-', '' -replace '-$', '' -} else { +} +else { # Generate from description with smart filtering $branchSuffix = Get-BranchName -Description $featureDesc } @@ -209,7 +218,8 @@ if ($Number -eq 0) { if ($hasGit) { # Check existing branches on remotes $Number = Get-NextBranchNumber -ShortName $branchSuffix -SpecsDir $specsDir - } else { + } + else { # Fall back to local directory check $highest = 0 if (Test-Path $specsDir) { @@ -251,10 +261,12 @@ if ($branchName.Length -gt $maxBranchLength) { if ($hasGit) { try { git checkout -b $branchName | Out-Null - } catch { + } + catch { Write-Warning "Failed to create git branch: $branchName" } -} else { +} +else { Write-Warning "[specify] Warning: Git repository not detected; skipped branch creation for $branchName" } @@ -265,7 +277,8 @@ $template = Join-Path $repoRoot '.specify/templates/spec-template.md' $specFile = Join-Path $featureDir 'spec.md' if (Test-Path $template) { Copy-Item $template $specFile -Force -} else { +} +else { New-Item -ItemType File -Path $specFile | Out-Null } @@ -275,12 +288,13 @@ $env:SPECIFY_FEATURE = $branchName if ($Json) { $obj = [PSCustomObject]@{ BRANCH_NAME = $branchName - SPEC_FILE = $specFile + SPEC_FILE = $specFile FEATURE_NUM = $featureNum - HAS_GIT = $hasGit + HAS_GIT = $hasGit } $obj | ConvertTo-Json -Compress -} else { +} +else { Write-Output "BRANCH_NAME: $branchName" Write-Output "SPEC_FILE: $specFile" Write-Output "FEATURE_NUM: $featureNum" diff --git a/.specify/scripts/powershell/update-agent-context.ps1 b/.specify/scripts/powershell/update-agent-context.ps1 index 695e28b8..a3cd6436 100644 --- a/.specify/scripts/powershell/update-agent-context.ps1 +++ b/.specify/scripts/powershell/update-agent-context.ps1 @@ -24,8 +24,8 @@ Optional agent key to update a single agent. If omitted, updates all existing ag Relies on common helper functions in common.ps1 #> param( - [Parameter(Position=0)] - [ValidateSet('claude','gemini','copilot','cursor-agent','qwen','opencode','codex','windsurf','kilocode','auggie','roo','codebuddy','amp','q')] + [Parameter(Position = 0)] + [ValidateSet('claude', 'gemini', 'copilot', 'cursor-agent', 'qwen', 'opencode', 'codex', 'windsurf', 'kilocode', 'auggie', 'roo', 'codebuddy', 'amp', 'q')] [string]$AgentType ) @@ -37,26 +37,26 @@ $ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path # Acquire environment paths $envData = Get-FeaturePathsEnv -$REPO_ROOT = $envData.REPO_ROOT +$REPO_ROOT = $envData.REPO_ROOT $CURRENT_BRANCH = $envData.CURRENT_BRANCH -$HAS_GIT = $envData.HAS_GIT -$IMPL_PLAN = $envData.IMPL_PLAN +$HAS_GIT = $envData.HAS_GIT +$IMPL_PLAN = $envData.IMPL_PLAN $NEW_PLAN = $IMPL_PLAN # Agent file paths -$CLAUDE_FILE = Join-Path $REPO_ROOT 'CLAUDE.md' -$GEMINI_FILE = Join-Path $REPO_ROOT 'GEMINI.md' -$COPILOT_FILE = Join-Path $REPO_ROOT '.github/copilot-instructions.md' -$CURSOR_FILE = Join-Path $REPO_ROOT '.cursor/rules/specify-rules.mdc' -$QWEN_FILE = Join-Path $REPO_ROOT 'QWEN.md' -$AGENTS_FILE = Join-Path $REPO_ROOT 'AGENTS.md' +$CLAUDE_FILE = Join-Path $REPO_ROOT 'CLAUDE.md' +$GEMINI_FILE = Join-Path $REPO_ROOT 'GEMINI.md' +$COPILOT_FILE = Join-Path $REPO_ROOT '.github/copilot-instructions.md' +$CURSOR_FILE = Join-Path $REPO_ROOT '.cursor/rules/specify-rules.mdc' +$QWEN_FILE = Join-Path $REPO_ROOT 'QWEN.md' +$AGENTS_FILE = Join-Path $REPO_ROOT 'AGENTS.md' $WINDSURF_FILE = Join-Path $REPO_ROOT '.windsurf/rules/specify-rules.md' $KILOCODE_FILE = Join-Path $REPO_ROOT '.kilocode/rules/specify-rules.md' -$AUGGIE_FILE = Join-Path $REPO_ROOT '.augment/rules/specify-rules.md' -$ROO_FILE = Join-Path $REPO_ROOT '.roo/rules/specify-rules.md' +$AUGGIE_FILE = Join-Path $REPO_ROOT '.augment/rules/specify-rules.md' +$ROO_FILE = Join-Path $REPO_ROOT '.roo/rules/specify-rules.md' $CODEBUDDY_FILE = Join-Path $REPO_ROOT 'CODEBUDDY.md' -$AMP_FILE = Join-Path $REPO_ROOT 'AGENTS.md' -$Q_FILE = Join-Path $REPO_ROOT 'AGENTS.md' +$AMP_FILE = Join-Path $REPO_ROOT 'AGENTS.md' +$Q_FILE = Join-Path $REPO_ROOT 'AGENTS.md' $TEMPLATE_FILE = Join-Path $REPO_ROOT '.specify/templates/agent-file-template.md' @@ -68,7 +68,7 @@ $script:NEW_PROJECT_TYPE = '' function Write-Info { param( - [Parameter(Mandatory=$true)] + [Parameter(Mandatory = $true)] [string]$Message ) Write-Host "INFO: $Message" @@ -76,7 +76,7 @@ function Write-Info { function Write-Success { param( - [Parameter(Mandatory=$true)] + [Parameter(Mandatory = $true)] [string]$Message ) Write-Host "$([char]0x2713) $Message" @@ -84,7 +84,7 @@ function Write-Success { function Write-WarningMsg { param( - [Parameter(Mandatory=$true)] + [Parameter(Mandatory = $true)] [string]$Message ) Write-Warning $Message @@ -92,7 +92,7 @@ function Write-WarningMsg { function Write-Err { param( - [Parameter(Mandatory=$true)] + [Parameter(Mandatory = $true)] [string]$Message ) Write-Host "ERROR: $Message" -ForegroundColor Red @@ -119,9 +119,9 @@ function Validate-Environment { function Extract-PlanField { param( - [Parameter(Mandatory=$true)] + [Parameter(Mandatory = $true)] [string]$FieldPattern, - [Parameter(Mandatory=$true)] + [Parameter(Mandatory = $true)] [string]$PlanFile ) if (-not (Test-Path $PlanFile)) { return '' } @@ -130,21 +130,21 @@ function Extract-PlanField { Get-Content -LiteralPath $PlanFile -Encoding utf8 | ForEach-Object { if ($_ -match $regex) { $val = $Matches[1].Trim() - if ($val -notin @('NEEDS CLARIFICATION','N/A')) { return $val } + if ($val -notin @('NEEDS CLARIFICATION', 'N/A')) { return $val } } } | Select-Object -First 1 } function Parse-PlanData { param( - [Parameter(Mandatory=$true)] + [Parameter(Mandatory = $true)] [string]$PlanFile ) if (-not (Test-Path $PlanFile)) { Write-Err "Plan file not found: $PlanFile"; return $false } Write-Info "Parsing plan data from $PlanFile" - $script:NEW_LANG = Extract-PlanField -FieldPattern 'Language/Version' -PlanFile $PlanFile - $script:NEW_FRAMEWORK = Extract-PlanField -FieldPattern 'Primary Dependencies' -PlanFile $PlanFile - $script:NEW_DB = Extract-PlanField -FieldPattern 'Storage' -PlanFile $PlanFile + $script:NEW_LANG = Extract-PlanField -FieldPattern 'Language/Version' -PlanFile $PlanFile + $script:NEW_FRAMEWORK = Extract-PlanField -FieldPattern 'Primary Dependencies' -PlanFile $PlanFile + $script:NEW_DB = Extract-PlanField -FieldPattern 'Storage' -PlanFile $PlanFile $script:NEW_PROJECT_TYPE = Extract-PlanField -FieldPattern 'Project Type' -PlanFile $PlanFile if ($NEW_LANG) { Write-Info "Found language: $NEW_LANG" } else { Write-WarningMsg 'No language information found in plan' } @@ -156,21 +156,21 @@ function Parse-PlanData { function Format-TechnologyStack { param( - [Parameter(Mandatory=$false)] + [Parameter(Mandatory = $false)] [string]$Lang, - [Parameter(Mandatory=$false)] + [Parameter(Mandatory = $false)] [string]$Framework ) $parts = @() if ($Lang -and $Lang -ne 'NEEDS CLARIFICATION') { $parts += $Lang } - if ($Framework -and $Framework -notin @('NEEDS CLARIFICATION','N/A')) { $parts += $Framework } + if ($Framework -and $Framework -notin @('NEEDS CLARIFICATION', 'N/A')) { $parts += $Framework } if (-not $parts) { return '' } return ($parts -join ' + ') } function Get-ProjectStructure { param( - [Parameter(Mandatory=$false)] + [Parameter(Mandatory = $false)] [string]$ProjectType ) if ($ProjectType -match 'web') { return "backend/`nfrontend/`ntests/" } else { return "src/`ntests/" } @@ -178,7 +178,7 @@ function Get-ProjectStructure { function Get-CommandsForLanguage { param( - [Parameter(Mandatory=$false)] + [Parameter(Mandatory = $false)] [string]$Lang ) switch -Regex ($Lang) { @@ -191,7 +191,7 @@ function Get-CommandsForLanguage { function Get-LanguageConventions { param( - [Parameter(Mandatory=$false)] + [Parameter(Mandatory = $false)] [string]$Lang ) if ($Lang) { "${Lang}: Follow standard conventions" } else { 'General: Follow standard conventions' } @@ -199,11 +199,11 @@ function Get-LanguageConventions { function New-AgentFile { param( - [Parameter(Mandatory=$true)] + [Parameter(Mandatory = $true)] [string]$TargetFile, - [Parameter(Mandatory=$true)] + [Parameter(Mandatory = $true)] [string]$ProjectName, - [Parameter(Mandatory=$true)] + [Parameter(Mandatory = $true)] [datetime]$Date ) if (-not (Test-Path $TEMPLATE_FILE)) { Write-Err "Template not found at $TEMPLATE_FILE"; return $false } @@ -219,40 +219,44 @@ function New-AgentFile { $escaped_branch = $CURRENT_BRANCH $content = Get-Content -LiteralPath $temp -Raw -Encoding utf8 - $content = $content -replace '\[PROJECT NAME\]',$ProjectName - $content = $content -replace '\[DATE\]',$Date.ToString('yyyy-MM-dd') + $content = $content -replace '\[PROJECT NAME\]', $ProjectName + $content = $content -replace '\[DATE\]', $Date.ToString('yyyy-MM-dd') # Build the technology stack string safely $techStackForTemplate = "" if ($escaped_lang -and $escaped_framework) { $techStackForTemplate = "- $escaped_lang + $escaped_framework ($escaped_branch)" - } elseif ($escaped_lang) { + } + elseif ($escaped_lang) { $techStackForTemplate = "- $escaped_lang ($escaped_branch)" - } elseif ($escaped_framework) { + } + elseif ($escaped_framework) { $techStackForTemplate = "- $escaped_framework ($escaped_branch)" } - $content = $content -replace '\[EXTRACTED FROM ALL PLAN.MD FILES\]',$techStackForTemplate + $content = $content -replace '\[EXTRACTED FROM ALL PLAN.MD FILES\]', $techStackForTemplate # For project structure we manually embed (keep newlines) $escapedStructure = [Regex]::Escape($projectStructure) - $content = $content -replace '\[ACTUAL STRUCTURE FROM PLANS\]',$escapedStructure + $content = $content -replace '\[ACTUAL STRUCTURE FROM PLANS\]', $escapedStructure # Replace escaped newlines placeholder after all replacements - $content = $content -replace '\[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES\]',$commands - $content = $content -replace '\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]',$languageConventions + $content = $content -replace '\[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES\]', $commands + $content = $content -replace '\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]', $languageConventions # Build the recent changes string safely $recentChangesForTemplate = "" if ($escaped_lang -and $escaped_framework) { $recentChangesForTemplate = "- ${escaped_branch}: Added ${escaped_lang} + ${escaped_framework}" - } elseif ($escaped_lang) { + } + elseif ($escaped_lang) { $recentChangesForTemplate = "- ${escaped_branch}: Added ${escaped_lang}" - } elseif ($escaped_framework) { + } + elseif ($escaped_framework) { $recentChangesForTemplate = "- ${escaped_branch}: Added ${escaped_framework}" } - $content = $content -replace '\[LAST 3 FEATURES AND WHAT THEY ADDED\]',$recentChangesForTemplate + $content = $content -replace '\[LAST 3 FEATURES AND WHAT THEY ADDED\]', $recentChangesForTemplate # Convert literal \n sequences introduced by Escape to real newlines - $content = $content -replace '\\n',[Environment]::NewLine + $content = $content -replace '\\n', [Environment]::NewLine $parent = Split-Path -Parent $TargetFile if (-not (Test-Path $parent)) { New-Item -ItemType Directory -Path $parent | Out-Null } @@ -263,9 +267,9 @@ function New-AgentFile { function Update-ExistingAgentFile { param( - [Parameter(Mandatory=$true)] + [Parameter(Mandatory = $true)] [string]$TargetFile, - [Parameter(Mandatory=$true)] + [Parameter(Mandatory = $true)] [datetime]$Date ) if (-not (Test-Path $TargetFile)) { return (New-AgentFile -TargetFile $TargetFile -ProjectName (Split-Path $REPO_ROOT -Leaf) -Date $Date) } @@ -278,7 +282,7 @@ function Update-ExistingAgentFile { $newTechEntries += "- $techStack ($CURRENT_BRANCH)" } } - if ($NEW_DB -and $NEW_DB -notin @('N/A','NEEDS CLARIFICATION')) { + if ($NEW_DB -and $NEW_DB -notin @('N/A', 'NEEDS CLARIFICATION')) { $escapedDB = [Regex]::Escape($NEW_DB) if (-not (Select-String -Pattern $escapedDB -Path $TargetFile -Quiet)) { $newTechEntries += "- $NEW_DB ($CURRENT_BRANCH)" @@ -286,13 +290,13 @@ function Update-ExistingAgentFile { } $newChangeEntry = '' if ($techStack) { $newChangeEntry = "- ${CURRENT_BRANCH}: Added ${techStack}" } - elseif ($NEW_DB -and $NEW_DB -notin @('N/A','NEEDS CLARIFICATION')) { $newChangeEntry = "- ${CURRENT_BRANCH}: Added ${NEW_DB}" } + elseif ($NEW_DB -and $NEW_DB -notin @('N/A', 'NEEDS CLARIFICATION')) { $newChangeEntry = "- ${CURRENT_BRANCH}: Added ${NEW_DB}" } $lines = Get-Content -LiteralPath $TargetFile -Encoding utf8 $output = New-Object System.Collections.Generic.List[string] $inTech = $false; $inChanges = $false; $techAdded = $false; $changeAdded = $false; $existingChanges = 0 - for ($i=0; $i -lt $lines.Count; $i++) { + for ($i = 0; $i -lt $lines.Count; $i++) { $line = $lines[$i] if ($line -eq '## Active Technologies') { $output.Add($line) @@ -319,7 +323,7 @@ function Update-ExistingAgentFile { continue } if ($line -match '\*\*Last updated\*\*: .*\d{4}-\d{2}-\d{2}') { - $output.Add(($line -replace '\d{4}-\d{2}-\d{2}',$Date.ToString('yyyy-MM-dd'))) + $output.Add(($line -replace '\d{4}-\d{2}-\d{2}', $Date.ToString('yyyy-MM-dd'))) continue } $output.Add($line) @@ -336,9 +340,9 @@ function Update-ExistingAgentFile { function Update-AgentFile { param( - [Parameter(Mandatory=$true)] + [Parameter(Mandatory = $true)] [string]$TargetFile, - [Parameter(Mandatory=$true)] + [Parameter(Mandatory = $true)] [string]$AgentName ) if (-not $TargetFile -or -not $AgentName) { Write-Err 'Update-AgentFile requires TargetFile and AgentName'; return $false } @@ -351,10 +355,12 @@ function Update-AgentFile { if (-not (Test-Path $TargetFile)) { if (New-AgentFile -TargetFile $TargetFile -ProjectName $projectName -Date $date) { Write-Success "Created new $AgentName context file" } else { Write-Err 'Failed to create new agent file'; return $false } - } else { + } + else { try { if (Update-ExistingAgentFile -TargetFile $TargetFile -Date $date) { Write-Success "Updated existing $AgentName context file" } else { Write-Err 'Failed to update agent file'; return $false } - } catch { + } + catch { Write-Err "Cannot access or update existing file: $TargetFile. $_" return $false } @@ -364,24 +370,24 @@ function Update-AgentFile { function Update-SpecificAgent { param( - [Parameter(Mandatory=$true)] + [Parameter(Mandatory = $true)] [string]$Type ) switch ($Type) { - 'claude' { Update-AgentFile -TargetFile $CLAUDE_FILE -AgentName 'Claude Code' } - 'gemini' { Update-AgentFile -TargetFile $GEMINI_FILE -AgentName 'Gemini CLI' } - 'copilot' { Update-AgentFile -TargetFile $COPILOT_FILE -AgentName 'GitHub Copilot' } + 'claude' { Update-AgentFile -TargetFile $CLAUDE_FILE -AgentName 'Claude Code' } + 'gemini' { Update-AgentFile -TargetFile $GEMINI_FILE -AgentName 'Gemini CLI' } + 'copilot' { Update-AgentFile -TargetFile $COPILOT_FILE -AgentName 'GitHub Copilot' } 'cursor-agent' { Update-AgentFile -TargetFile $CURSOR_FILE -AgentName 'Cursor IDE' } - 'qwen' { Update-AgentFile -TargetFile $QWEN_FILE -AgentName 'Qwen Code' } + 'qwen' { Update-AgentFile -TargetFile $QWEN_FILE -AgentName 'Qwen Code' } 'opencode' { Update-AgentFile -TargetFile $AGENTS_FILE -AgentName 'opencode' } - 'codex' { Update-AgentFile -TargetFile $AGENTS_FILE -AgentName 'Codex CLI' } + 'codex' { Update-AgentFile -TargetFile $AGENTS_FILE -AgentName 'Codex CLI' } 'windsurf' { Update-AgentFile -TargetFile $WINDSURF_FILE -AgentName 'Windsurf' } 'kilocode' { Update-AgentFile -TargetFile $KILOCODE_FILE -AgentName 'Kilo Code' } - 'auggie' { Update-AgentFile -TargetFile $AUGGIE_FILE -AgentName 'Auggie CLI' } - 'roo' { Update-AgentFile -TargetFile $ROO_FILE -AgentName 'Roo Code' } + 'auggie' { Update-AgentFile -TargetFile $AUGGIE_FILE -AgentName 'Auggie CLI' } + 'roo' { Update-AgentFile -TargetFile $ROO_FILE -AgentName 'Roo Code' } 'codebuddy' { Update-AgentFile -TargetFile $CODEBUDDY_FILE -AgentName 'CodeBuddy CLI' } - 'amp' { Update-AgentFile -TargetFile $AMP_FILE -AgentName 'Amp' } - 'q' { Update-AgentFile -TargetFile $Q_FILE -AgentName 'Amazon Q Developer CLI' } + 'amp' { Update-AgentFile -TargetFile $AMP_FILE -AgentName 'Amp' } + 'q' { Update-AgentFile -TargetFile $Q_FILE -AgentName 'Amazon Q Developer CLI' } default { Write-Err "Unknown agent type '$Type'"; Write-Err 'Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|q'; return $false } } } @@ -389,18 +395,18 @@ function Update-SpecificAgent { function Update-AllExistingAgents { $found = $false $ok = $true - if (Test-Path $CLAUDE_FILE) { if (-not (Update-AgentFile -TargetFile $CLAUDE_FILE -AgentName 'Claude Code')) { $ok = $false }; $found = $true } - if (Test-Path $GEMINI_FILE) { if (-not (Update-AgentFile -TargetFile $GEMINI_FILE -AgentName 'Gemini CLI')) { $ok = $false }; $found = $true } - if (Test-Path $COPILOT_FILE) { if (-not (Update-AgentFile -TargetFile $COPILOT_FILE -AgentName 'GitHub Copilot')) { $ok = $false }; $found = $true } - if (Test-Path $CURSOR_FILE) { if (-not (Update-AgentFile -TargetFile $CURSOR_FILE -AgentName 'Cursor IDE')) { $ok = $false }; $found = $true } - if (Test-Path $QWEN_FILE) { if (-not (Update-AgentFile -TargetFile $QWEN_FILE -AgentName 'Qwen Code')) { $ok = $false }; $found = $true } - if (Test-Path $AGENTS_FILE) { if (-not (Update-AgentFile -TargetFile $AGENTS_FILE -AgentName 'Codex/opencode')) { $ok = $false }; $found = $true } + if (Test-Path $CLAUDE_FILE) { if (-not (Update-AgentFile -TargetFile $CLAUDE_FILE -AgentName 'Claude Code')) { $ok = $false }; $found = $true } + if (Test-Path $GEMINI_FILE) { if (-not (Update-AgentFile -TargetFile $GEMINI_FILE -AgentName 'Gemini CLI')) { $ok = $false }; $found = $true } + if (Test-Path $COPILOT_FILE) { if (-not (Update-AgentFile -TargetFile $COPILOT_FILE -AgentName 'GitHub Copilot')) { $ok = $false }; $found = $true } + if (Test-Path $CURSOR_FILE) { if (-not (Update-AgentFile -TargetFile $CURSOR_FILE -AgentName 'Cursor IDE')) { $ok = $false }; $found = $true } + if (Test-Path $QWEN_FILE) { if (-not (Update-AgentFile -TargetFile $QWEN_FILE -AgentName 'Qwen Code')) { $ok = $false }; $found = $true } + if (Test-Path $AGENTS_FILE) { if (-not (Update-AgentFile -TargetFile $AGENTS_FILE -AgentName 'Codex/opencode')) { $ok = $false }; $found = $true } if (Test-Path $WINDSURF_FILE) { if (-not (Update-AgentFile -TargetFile $WINDSURF_FILE -AgentName 'Windsurf')) { $ok = $false }; $found = $true } if (Test-Path $KILOCODE_FILE) { if (-not (Update-AgentFile -TargetFile $KILOCODE_FILE -AgentName 'Kilo Code')) { $ok = $false }; $found = $true } - if (Test-Path $AUGGIE_FILE) { if (-not (Update-AgentFile -TargetFile $AUGGIE_FILE -AgentName 'Auggie CLI')) { $ok = $false }; $found = $true } - if (Test-Path $ROO_FILE) { if (-not (Update-AgentFile -TargetFile $ROO_FILE -AgentName 'Roo Code')) { $ok = $false }; $found = $true } + if (Test-Path $AUGGIE_FILE) { if (-not (Update-AgentFile -TargetFile $AUGGIE_FILE -AgentName 'Auggie CLI')) { $ok = $false }; $found = $true } + if (Test-Path $ROO_FILE) { if (-not (Update-AgentFile -TargetFile $ROO_FILE -AgentName 'Roo Code')) { $ok = $false }; $found = $true } if (Test-Path $CODEBUDDY_FILE) { if (-not (Update-AgentFile -TargetFile $CODEBUDDY_FILE -AgentName 'CodeBuddy CLI')) { $ok = $false }; $found = $true } - if (Test-Path $Q_FILE) { if (-not (Update-AgentFile -TargetFile $Q_FILE -AgentName 'Amazon Q Developer CLI')) { $ok = $false }; $found = $true } + if (Test-Path $Q_FILE) { if (-not (Update-AgentFile -TargetFile $Q_FILE -AgentName 'Amazon Q Developer CLI')) { $ok = $false }; $found = $true } if (-not $found) { Write-Info 'No existing agent files found, creating default Claude file...' if (-not (Update-AgentFile -TargetFile $CLAUDE_FILE -AgentName 'Claude Code')) { $ok = $false }