diff --git a/CHANGELOG.md b/CHANGELOG.md index 125a68b4..d9485cb4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,20 @@ All notable changes to the Specify CLI will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [LATEST_VERSION] - RELEASE_DATE + +### Added + +- Support for using `.` as a shorthand for current directory in `specify init .` command, equivalent to `--here` flag but more intuitive for users + +## [0.0.17] - 2025-09-22 + +### Added + +- New `/clarify` command template to surface up to 5 targeted clarification questions for an existing spec and persist answers into a Clarifications section in the spec. +- New `/analyze` command template providing a non-destructive cross-artifact discrepancy and alignment report (spec, clarifications, plan, tasks, constitution) inserted after `/tasks` and before `/implement`. + - Note: Constitution rules are explicitly treated as non-negotiable; any conflict is a CRITICAL finding requiring artifact remediation, not weakening of principles. + ## [0.0.16] - 2025-09-22 ### Added diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 17baec85..bf65fa77 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -47,12 +47,40 @@ When working on spec-kit: ## AI contributions in Spec Kit +> [!IMPORTANT] +> +> If you are using **any kind of AI assistance** to contribute to Spec Kit, +> it must be disclosed in the pull request or issue. + We welcome and encourage the use of AI tools to help improve Spec Kit! Many valuable contributions have been enhanced with AI assistance for code generation, issue detection, and feature definition. +That being said, if you are using any kind of AI assistance (e.g., agents, ChatGPT) while contributing to Spec Kit, +**this must be disclosed in the pull request or issue**, along with the extent to which AI assistance was used (e.g., documentation comments vs. code generation). + +If your PR responses or comments are being generated by an AI, disclose that as well. + +As an exception, trivial spacing or typo fixes don't need to be disclosed, so long as the changes are limited to small parts of the code or short phrases. + +An example disclosure: + +> This PR was written primarily by GitHub Copilot. + +Or a more detailed disclosure: + +> I consulted ChatGPT to understand the codebase but the solution +> was fully authored manually by myself. + +Failure to disclose this is first and foremost rude to the human operators on the other end of the pull request, but it also makes it difficult to +determine how much scrutiny to apply to the contribution. + +In a perfect world, AI assistance would produce equal or higher quality work than any human. That isn't the world we live in today, and in most cases +where human supervision or expertise is not in the loop, it's generating code that cannot be reasonably maintained or evolved. + ### What we're looking for When submitting AI-assisted contributions, please ensure they include: +- **Clear disclosure of AI use** - You are transparent about AI use and degree to which you're using it for the contribution - **Human understanding and testing** - You've personally tested the changes and understand what they do - **Clear rationale** - You can explain why the change is needed and how it fits within Spec Kit's goals - **Concrete evidence** - Include test cases, scenarios, or examples that demonstrate the improvement @@ -72,6 +100,8 @@ The key is demonstrating that you understand and have validated your proposed ch Contributors who consistently submit low-effort AI-generated changes may be restricted from further contributions at the maintainers' discretion. +Please be respectful to maintainers and disclose AI assistance. + ## Resources - [Spec-Driven Development Methodology](./spec-driven.md) diff --git a/README.md b/README.md index 47e0c720..faed3cc3 100644 --- a/README.md +++ b/README.md @@ -151,13 +151,13 @@ The `specify` command supports the following options: | Argument/Option | Type | Description | |------------------------|----------|------------------------------------------------------------------------------| -| `` | Argument | Name for your new project directory (optional if using `--here`) | +| `` | Argument | Name for your new project directory (optional if using `--here`, or use `.` for current directory) | | `--ai` | Option | AI assistant to use: `claude`, `gemini`, `copilot`, `cursor`, `qwen`, `opencode`, `codex`, `windsurf`, `kilocode`, `auggie`, `roo`, or `codebuddy` | | `--script` | Option | Script variant to use: `sh` (bash/zsh) or `ps` (PowerShell) | | `--ignore-agent-tools` | Flag | Skip checks for AI agent tools like Claude Code | | `--no-git` | Flag | Skip git repository initialization | | `--here` | Flag | Initialize project in the current directory instead of creating a new one | -| `--force` | Flag | Force merge/overwrite when using `--here` in a non-empty directory (skip confirmation) | +| `--force` | Flag | Force merge/overwrite when initializing in current directory (skip confirmation) | | `--skip-tls` | Flag | Skip SSL/TLS verification (not recommended) | | `--debug` | Flag | Enable detailed debug output for troubleshooting | | `--github-token` | Option | GitHub token for API requests (or set GH_TOKEN/GITHUB_TOKEN env variable) | @@ -181,9 +181,13 @@ specify init my-project --ai windsurf specify init my-project --ai copilot --script ps # Initialize in current directory +specify init . --ai copilot +# or use the --here flag specify init --here --ai copilot # Force merge into current (non-empty) directory without confirmation +specify init . --force --ai copilot +# or specify init --here --force --ai copilot # Skip git initialization @@ -207,8 +211,10 @@ After running `specify init`, your AI coding agent will have access to these sla |-----------------|-----------------------------------------------------------------------| | `/constitution` | Create or update project governing principles and development guidelines | | `/specify` | Define what you want to build (requirements and user stories) | +| `/clarify` | Clarify underspecified areas (must be run before `/plan` unless explicitly skipped; formerly `/quizme`) | | `/plan` | Create technical implementation plans with your chosen tech stack | | `/tasks` | Generate actionable task lists for implementation | +| `/analyze` | Cross-artifact consistency & coverage analysis (run after /tasks, before /implement) | | `/implement` | Execute all tasks to build the feature according to the plan | ### Environment Variables @@ -291,8 +297,12 @@ specify init Or initialize in the current directory: ```bash +specify init . +# or use the --here flag specify init --here # Skip confirmation when the directory already has files +specify init . --force +# or specify init --here --force ``` @@ -311,9 +321,14 @@ specify init --ai codex specify init --ai windsurf specify init --ai codebuddy # Or in current directory: +specify init . --ai claude +specify init . --ai codex +# or use --here flag specify init --here --ai claude specify init --here --ai codex # Force merge into a non-empty current directory +specify init . --force --ai claude +# or specify init --here --force --ai claude ``` @@ -337,7 +352,7 @@ The first step should be establishing your project's governing principles using /constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements. Include governance for how these principles should guide technical decisions and implementation choices. ``` -This step creates or updates the `/memory/constitution.md` file with your project's foundational guidelines that the AI agent will reference during specification, planning, and implementation phases. +This step creates or updates the `.specify/memory/constitution.md` file with your project's foundational guidelines that the AI agent will reference during specification, planning, and implementation phases. ### **STEP 2:** Create project specifications @@ -376,27 +391,37 @@ The produced specification should contain a set of user stories and functional r At this stage, your project folder contents should resemble the following: ```text -├── memory -│ ├── constitution.md -│ └── constitution_update_checklist.md -├── scripts -│ ├── check-prerequisites.sh -│ ├── common.sh -│ ├── create-new-feature.sh -│ ├── setup-plan.sh -│ └── update-claude-md.sh -├── specs -│ └── 001-create-taskify -│ └── spec.md -└── templates - ├── plan-template.md - ├── spec-template.md - └── tasks-template.md +└── .specify + ├── memory + │ └── constitution.md + ├── scripts + │ ├── check-prerequisites.sh + │ ├── common.sh + │ ├── create-new-feature.sh + │ ├── setup-plan.sh + │ └── update-claude-md.sh + ├── specs + │ └── 001-create-taskify + │ └── spec.md + └── templates + ├── plan-template.md + ├── spec-template.md + └── tasks-template.md ``` -### **STEP 3:** Functional specification clarification +### **STEP 3:** Functional specification clarification (required before planning) -With the baseline specification created, you can go ahead and clarify any of the requirements that were not captured properly within the first shot attempt. For example, you could use a prompt like this within the same Claude Code session: +With the baseline specification created, you can go ahead and clarify any of the requirements that were not captured properly within the first shot attempt. + +You should run the structured clarification workflow **before** creating a technical plan to reduce rework downstream. + +Preferred order: +1. Use `/clarify` (structured) – sequential, coverage-based questioning that records answers in a Clarifications section. +2. Optionally follow up with ad-hoc free-form refinement if something still feels vague. + +If you intentionally want to skip clarification (e.g., spike or exploratory prototype), explicitly state that so the agent doesn't block on missing clarifications. + +Example free-form refinement prompt (after `/clarify` if still needed): ```text For each sample project or project that you create there should be a variable number of tasks between 5 and 15 @@ -428,8 +453,7 @@ The output of this step will include a number of implementation detail documents . ├── CLAUDE.md ├── memory -│ ├── constitution.md -│ └── constitution_update_checklist.md +│ └── constitution.md ├── scripts │ ├── check-prerequisites.sh │ ├── common.sh diff --git a/docs/installation.md b/docs/installation.md index 7cf9a6ae..b30b0948 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -21,6 +21,8 @@ uvx --from git+https://github.com/github/spec-kit.git specify init + uvx specify-cli.py init . uvx specify-cli.py init --here Or install globally: uv tool install --from specify-cli.py specify-cli specify init + specify init . specify init --here """ @@ -193,9 +195,9 @@ def get_key(): key = readchar.readkey() # Arrow keys - if key == readchar.key.UP: + if key == readchar.key.UP or key == readchar.key.CTRL_P: return 'up' - if key == readchar.key.DOWN: + if key == readchar.key.DOWN or key == readchar.key.CTRL_N: return 'down' # Enter/Return @@ -748,7 +750,7 @@ def ensure_executable_scripts(project_path: Path, tracker: StepTracker | None = @app.command() def init( - project_name: str = typer.Argument(None, help="Name for your new project directory (optional if using --here)"), + project_name: str = typer.Argument(None, help="Name for your new project directory (optional if using --here, or use '.' for current directory)"), ai_assistant: str = typer.Option(None, "--ai", help="AI assistant to use: claude, gemini, copilot, cursor, qwen, opencode, codex, windsurf, kilocode, auggie, roo, or codebuddy"), script_type: str = typer.Option(None, "--script", help="Script type to use: sh or ps"), ignore_agent_tools: bool = typer.Option(False, "--ignore-agent-tools", help="Skip checks for AI agent tools like Claude Code"), @@ -784,7 +786,9 @@ def init( specify init my-project --ai auggie specify init my-project --ai codebuddy specify init --ignore-agent-tools my-project - specify init --here --ai claude + specify init . --ai claude # Initialize in current directory + specify init . # Initialize in current directory (interactive AI selection) + specify init --here --ai claude # Alternative syntax for current directory specify init --here --ai codex specify init --here --ai codebuddy specify init --here @@ -793,13 +797,18 @@ def init( # Show banner first show_banner() + # Handle '.' as shorthand for current directory (equivalent to --here) + if project_name == ".": + here = True + project_name = None # Clear project_name to use existing validation logic + # Validate arguments if here and project_name: console.print("[red]Error:[/red] Cannot specify both project name and --here flag") raise typer.Exit(1) if not here and not project_name: - console.print("[red]Error:[/red] Must specify either a project name or use --here flag") + console.print("[red]Error:[/red] Must specify either a project name, use '.' for current directory, or use --here flag") raise typer.Exit(1) # Determine project directory @@ -1067,9 +1076,10 @@ def init( step_num += 1 steps_lines.append(f"{step_num}. Start using slash commands with your AI agent:") + steps_lines.append(" 2.1 [cyan]/constitution[/] - Establish project principles") - steps_lines.append(" 2.2 [cyan]/specify[/] - Create specifications") - steps_lines.append(" 2.3 [cyan]/plan[/] - Create implementation plans") + steps_lines.append(" 2.2 [cyan]/specify[/] - Create baseline specification") + steps_lines.append(" 2.3 [cyan]/plan[/] - Create implementation plan") steps_lines.append(" 2.4 [cyan]/tasks[/] - Generate actionable tasks") steps_lines.append(" 2.5 [cyan]/implement[/] - Execute implementation") @@ -1077,6 +1087,16 @@ def init( console.print() console.print(steps_panel) + enhancement_lines = [ + "Optional commands that you can use for your specs [bright_black](improve quality & confidence)[/bright_black]", + "", + f"○ [cyan]/clarify[/] [bright_black](optional)[/bright_black] - Ask structured questions to de-risk ambiguous areas before planning (run before [cyan]/plan[/] if used)", + f"○ [cyan]/analyze[/] [bright_black](optional)[/bright_black] - Cross-artifact consistency & alignment report (after [cyan]/tasks[/], before [cyan]/implement[/])" + ] + enhancements_panel = Panel("\n".join(enhancement_lines), title="Enhancement Commands", border_style="cyan", padding=(1,2)) + console.print() + console.print(enhancements_panel) + if selected_ai == "codex": warning_text = """[bold yellow]Important Note:[/bold yellow] diff --git a/templates/commands/analyze.md b/templates/commands/analyze.md new file mode 100644 index 00000000..c07d550b --- /dev/null +++ b/templates/commands/analyze.md @@ -0,0 +1,104 @@ +--- +description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation. +scripts: + sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks + ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks +--- + +The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty). + +User input: + +$ARGUMENTS + +Goal: Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/tasks` has successfully produced a complete `tasks.md`. + +STRICTLY READ-ONLY: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually). + +Constitution Authority: The project constitution (`/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/analyze`. + +Execution steps: + +1. Run `{SCRIPT}` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths: + - SPEC = FEATURE_DIR/spec.md + - PLAN = FEATURE_DIR/plan.md + - TASKS = FEATURE_DIR/tasks.md + Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command). + +2. Load artifacts: + - Parse spec.md sections: Overview/Context, Functional Requirements, Non-Functional Requirements, User Stories, Edge Cases (if present). + - Parse plan.md: Architecture/stack choices, Data Model references, Phases, Technical constraints. + - Parse tasks.md: Task IDs, descriptions, phase grouping, parallel markers [P], referenced file paths. + - Load constitution `/memory/constitution.md` for principle validation. + +3. Build internal semantic models: + - Requirements inventory: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" -> `user-can-upload-file`). + - User story/action inventory. + - Task coverage mapping: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases). + - Constitution rule set: Extract principle names and any MUST/SHOULD normative statements. + +4. Detection passes: + A. Duplication detection: + - Identify near-duplicate requirements. Mark lower-quality phrasing for consolidation. + B. Ambiguity detection: + - Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria. + - Flag unresolved placeholders (TODO, TKTK, ???, , etc.). + C. Underspecification: + - Requirements with verbs but missing object or measurable outcome. + - User stories missing acceptance criteria alignment. + - Tasks referencing files or components not defined in spec/plan. + D. Constitution alignment: + - Any requirement or plan element conflicting with a MUST principle. + - Missing mandated sections or quality gates from constitution. + E. Coverage gaps: + - Requirements with zero associated tasks. + - Tasks with no mapped requirement/story. + - Non-functional requirements not reflected in tasks (e.g., performance, security). + F. Inconsistency: + - Terminology drift (same concept named differently across files). + - Data entities referenced in plan but absent in spec (or vice versa). + - Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note). + - Conflicting requirements (e.g., one requires to use Next.js while other says to use Vue as the framework). + +5. Severity assignment heuristic: + - CRITICAL: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality. + - HIGH: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion. + - MEDIUM: Terminology drift, missing non-functional task coverage, underspecified edge case. + - LOW: Style/wording improvements, minor redundancy not affecting execution order. + +6. Produce a Markdown report (no file writes) with sections: + + ### Specification Analysis Report + | ID | Category | Severity | Location(s) | Summary | Recommendation | + |----|----------|----------|-------------|---------|----------------| + | A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version | + (Add one row per finding; generate stable IDs prefixed by category initial.) + + Additional subsections: + - Coverage Summary Table: + | Requirement Key | Has Task? | Task IDs | Notes | + - Constitution Alignment Issues (if any) + - Unmapped Tasks (if any) + - Metrics: + * Total Requirements + * Total Tasks + * Coverage % (requirements with >=1 task) + * Ambiguity Count + * Duplication Count + * Critical Issues Count + +7. At end of report, output a concise Next Actions block: + - If CRITICAL issues exist: Recommend resolving before `/implement`. + - If only LOW/MEDIUM: User may proceed, but provide improvement suggestions. + - Provide explicit command suggestions: e.g., "Run /specify with refinement", "Run /plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'". + +8. Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.) + +Behavior rules: +- NEVER modify files. +- NEVER hallucinate missing sections—if absent, report them. +- KEEP findings deterministic: if rerun without changes, produce consistent IDs and counts. +- LIMIT total findings in the main table to 50; aggregate remainder in a summarized overflow note. +- If zero issues found, emit a success report with coverage statistics and proceed recommendation. + +Context: {ARGS} diff --git a/templates/commands/clarify.md b/templates/commands/clarify.md new file mode 100644 index 00000000..e3f4a79d --- /dev/null +++ b/templates/commands/clarify.md @@ -0,0 +1,161 @@ +--- +description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec. +scripts: + sh: scripts/bash/check-prerequisites.sh --json --paths-only + ps: scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly +--- + +The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty). + +User input: + +$ARGUMENTS + +Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file. + +Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases. + +Execution steps: + +1. Run `{SCRIPT}` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields: + - `FEATURE_DIR` + - `FEATURE_SPEC` + - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.) + - If JSON parsing fails, abort and instruct user to re-run `/specify` or verify feature branch environment. + +2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked). + + Functional Scope & Behavior: + - Core user goals & success criteria + - Explicit out-of-scope declarations + - User roles / personas differentiation + + Domain & Data Model: + - Entities, attributes, relationships + - Identity & uniqueness rules + - Lifecycle/state transitions + - Data volume / scale assumptions + + Interaction & UX Flow: + - Critical user journeys / sequences + - Error/empty/loading states + - Accessibility or localization notes + + Non-Functional Quality Attributes: + - Performance (latency, throughput targets) + - Scalability (horizontal/vertical, limits) + - Reliability & availability (uptime, recovery expectations) + - Observability (logging, metrics, tracing signals) + - Security & privacy (authN/Z, data protection, threat assumptions) + - Compliance / regulatory constraints (if any) + + Integration & External Dependencies: + - External services/APIs and failure modes + - Data import/export formats + - Protocol/versioning assumptions + + Edge Cases & Failure Handling: + - Negative scenarios + - Rate limiting / throttling + - Conflict resolution (e.g., concurrent edits) + + Constraints & Tradeoffs: + - Technical constraints (language, storage, hosting) + - Explicit tradeoffs or rejected alternatives + + Terminology & Consistency: + - Canonical glossary terms + - Avoided synonyms / deprecated terms + + Completion Signals: + - Acceptance criteria testability + - Measurable Definition of Done style indicators + + Misc / Placeholders: + - TODO markers / unresolved decisions + - Ambiguous adjectives ("robust", "intuitive") lacking quantification + + For each category with Partial or Missing status, add a candidate question opportunity unless: + - Clarification would not materially change implementation or validation strategy + - Information is better deferred to planning phase (note internally) + +3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints: + - Maximum of 5 total questions across the whole session. + - Each question must be answerable with EITHER: + * A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR + * A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words"). + - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation. + - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved. + - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness). + - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests. + - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic. + +4. Sequential questioning loop (interactive): + - Present EXACTLY ONE question at a time. + - For multiple‑choice questions render options as a Markdown table: + + | Option | Description | + |--------|-------------| + | A |