From f532446e7b4ef370bcec62a3d55d13181292b8fb Mon Sep 17 00:00:00 2001 From: csjones Date: Sat, 1 Nov 2025 21:52:26 -0800 Subject: [PATCH 01/10] Redo subtree --- .windsurf/rules/architecture.md | 193 ++ .windsurf/rules/bootstrap.md | 120 ++ .windsurf/rules/ci-cd.md | 115 ++ .windsurf/rules/compliance-check.md | 5 + .windsurf/workflows/analyze.md | 101 -- .windsurf/workflows/implement.md | 56 - .windsurf/workflows/plan.md | 43 - .windsurf/workflows/specify.md | 21 - .windsurf/workflows/speckit.analyze.md | 184 ++ .windsurf/workflows/speckit.checklist.md | 294 +++ .../{clarify.md => speckit.clarify.md} | 91 +- ...onstitution.md => speckit.constitution.md} | 19 +- .windsurf/workflows/speckit.implement.md | 134 ++ .windsurf/workflows/speckit.plan.md | 81 + .windsurf/workflows/speckit.roadmap.md | 201 +++ .windsurf/workflows/speckit.specify.md | 249 +++ .windsurf/workflows/speckit.tasks.md | 128 ++ .windsurf/workflows/tasks.md | 62 - Package.swift | 62 +- Sources/Subtree/Commands/AddCommand.swift | 343 ---- Sources/Subtree/Commands/ExtractCommand.swift | 284 --- Sources/Subtree/Commands/InitCommand.swift | 175 -- Sources/Subtree/Commands/RemoveCommand.swift | 152 -- Sources/Subtree/Commands/SubtreeCLI.swift | 28 - Sources/Subtree/Commands/UpdateCommand.swift | 542 ------ .../Subtree/Commands/ValidateCommand.swift | 210 --- Sources/Subtree/Git/GitPlumbing.swift | 427 ----- Sources/Subtree/IO/ConfigIO.swift | 112 -- Sources/Subtree/Models/CopyMapping.swift | 14 - Sources/Subtree/Models/SubtreeConfig.swift | 13 - Sources/Subtree/Models/SubtreeEntry.swift | 31 - Sources/Subtree/Models/SubtreeError.swift | 46 - Sources/Subtree/Models/UpdatePolicy.swift | 25 - .../Utilities/CommitMessageBuilder.swift | 209 --- .../Subtree/Utilities/RemoteURLParser.swift | 53 - Sources/Subtree/main.swift | 12 - Sources/SubtreeLib/Commands/AddCommand.swift | 238 +++ .../SubtreeLib/Commands/ExtractCommand.swift | 744 ++++++++ Sources/SubtreeLib/Commands/InitCommand.swift | 134 ++ .../SubtreeLib/Commands/RemoveCommand.swift | 145 ++ .../SubtreeLib/Commands/SubtreeCommand.swift | 28 + .../SubtreeLib/Commands/UpdateCommand.swift | 450 +++++ .../SubtreeLib/Commands/ValidateCommand.swift | 15 + .../Configuration/ExtractionMapping.swift | 26 + .../Configuration/Models/ExtractPattern.swift | 30 + .../Models/SubtreeConfiguration.swift | 86 + .../Configuration/Models/SubtreeEntry.swift | 65 + .../Parsing/ConfigurationParser.swift | 59 + .../Parsing/YAMLErrorTranslator.swift | 66 + .../Patterns/GlobPatternValidator.swift | 113 ++ .../Validation/ConfigurationValidator.swift | 48 + .../Validation/FormatValidator.swift | 152 ++ .../Validation/LogicValidator.swift | 66 + .../Validation/SchemaValidator.swift | 24 + .../Validation/TypeValidator.swift | 65 + .../Validation/ValidationError.swift | 50 + .../Utilities/CommitMessageFormatter.swift | 87 + .../Utilities/ConfigFileManager.swift | 164 ++ Sources/SubtreeLib/Utilities/ExitCode.swift | 22 + .../SubtreeLib/Utilities/GitOperations.swift | 212 +++ .../SubtreeLib/Utilities/GlobMatcher.swift | 352 ++++ .../SubtreeLib/Utilities/NameSanitizer.swift | 31 + .../SubtreeLib/Utilities/NameValidator.swift | 38 + .../SubtreeLib/Utilities/PathValidator.swift | 44 + .../Utilities/StringExtensions.swift | 45 + .../Utilities/SubtreeValidationError.swift | 113 ++ Sources/SubtreeLib/Utilities/URLParser.swift | 58 + Sources/subtree/EntryPoint.swift | 10 + .../Add/AddOverrideTests.swift | 260 --- .../Add/AddSmartDefaultsTests.swift | 269 --- Tests/IntegrationTests/Add/AddTests.swift | 126 -- .../AddIntegrationTests.swift | 1092 +++++++++++ .../Config/ConfigUpdateTests.swift | 184 -- .../Copy/CopyAdvancedTests.swift | 224 --- Tests/IntegrationTests/Copy/CopyTests.swift | 187 -- .../ExtractIntegrationTests.swift | 1590 +++++++++++++++++ .../Git/GitValidationTests.swift | 97 - Tests/IntegrationTests/GitFixtureTests.swift | 168 ++ .../GitRepositoryFixture.swift | 149 ++ .../Init/InitExtensionsTests.swift | 54 - Tests/IntegrationTests/Init/InitTests.swift | 75 - .../InitCommandIntegrationTests.swift | 477 +++++ .../Remove/RemoveEnhancedTests.swift | 303 ---- .../IntegrationTests/Remove/RemoveTests.swift | 131 -- .../RemoveIntegrationTests.swift | 606 +++++++ .../SubtreeIntegrationTests.swift | 84 + Tests/IntegrationTests/TestHarness.swift | 159 ++ .../TestUtils/RepoFixture.swift | 121 -- .../TestUtils/SubprocessHelpers.swift | 71 - .../Update/UpdateAdvancedTests.swift | 192 -- .../Update/UpdateApplyTests.swift | 206 --- .../Update/UpdateBasicTests.swift | 153 -- .../Update/UpdateBranchTests.swift | 254 --- .../Update/UpdateNetworkTests.swift | 126 -- .../Update/UpdateOverrideTests.swift | 187 -- .../Update/UpdateReportTests.swift | 187 -- .../Update/UpdateSafetyTests.swift | 206 --- .../UpdateCommandIntegrationTests.swift | 748 ++++++++ .../Utilities/CommitMessageBuilderTests.swift | 158 -- .../Utilities/RemoteURLParserTests.swift | 149 -- .../IntegrationTests/Verify/VerifyTests.swift | 209 --- Tests/SubtreeLibTests/CommandTests.swift | 33 + .../Commands/AddCommandTests.swift | 15 + .../Commands/ExtractCommandTests.swift | 472 +++++ .../Commands/RemoveCommandTests.swift | 236 +++ .../ConfigFileManagerTests.swift | 241 +++ .../ConfigValidationIntegrationTests.swift | 254 +++ .../ExtractionMappingTests.swift | 127 ++ .../Models/ExtractPatternTests.swift | 57 + .../Models/SubtreeConfigurationTests.swift | 61 + .../Models/SubtreeEntryTests.swift | 169 ++ .../Parsing/ConfigurationParserTests.swift | 60 + .../Parsing/YAMLErrorTranslatorTests.swift | 46 + .../Patterns/GlobPatternValidatorTests.swift | 97 + .../SubtreeConfigurationValidationTests.swift | 228 +++ .../Validation/FormatValidatorTests.swift | 111 ++ .../Validation/LogicValidatorTests.swift | 136 ++ .../Validation/SchemaValidatorTests.swift | 43 + .../Validation/TypeValidatorTests.swift | 106 ++ .../Validation/ValidationErrorTests.swift | 70 + Tests/SubtreeLibTests/ExitCodeTests.swift | 62 + .../SubtreeLibTests/GitOperationsTests.swift | 109 ++ .../CommitMessageFormatterTests.swift | 61 + .../Utilities/GlobMatcherTests.swift | 279 +++ .../Utilities/NameSanitizerTests.swift | 40 + .../Utilities/NameValidatorTests.swift | 102 ++ .../Utilities/PathValidatorTests.swift | 188 ++ .../Utilities/StringExtensionsTests.swift | 136 ++ .../SubtreeValidationErrorTests.swift | 215 +++ .../Utilities/URLParserTests.swift | 84 + .../Utilities/CommitMessageBuilderTests.swift | 158 -- .../Utilities/RemoteURLParserTests.swift | 149 -- agents.md | 235 +++ .../checklists/requirements.md | 46 + .../contracts/cli-commands.md | 332 ++++ specs/001-cli-bootstrap/data-model.md | 40 + specs/001-cli-bootstrap/plan.md | 212 +++ specs/001-cli-bootstrap/quickstart.md | 339 ++++ specs/001-cli-bootstrap/research.md | 206 +++ specs/001-cli-bootstrap/spec.md | 172 ++ specs/001-cli-bootstrap/tasks.md | 343 ++++ .../contracts/cli-commands.md | 142 -- specs/001-i-am-building/data-model.md | 87 - specs/001-i-am-building/plan.md | 223 --- specs/001-i-am-building/quickstart.md | 101 -- specs/001-i-am-building/research.md | 38 - specs/001-i-am-building/spec.md | 153 -- specs/001-i-am-building/tasks.md | 596 ------ .../checklists/requirements.md | 86 + .../contracts/validation-error-format.md | 441 +++++ .../contracts/yaml-schema.md | 392 ++++ .../data-model.md | 374 ++++ specs/002-config-schema-validation/plan.md | 237 +++ .../quickstart.md | 544 ++++++ .../002-config-schema-validation/research.md | 261 +++ specs/002-config-schema-validation/spec.md | 175 ++ specs/002-config-schema-validation/tasks.md | 352 ++++ .../checklists/requirements.md | 45 + .../contracts/cli-contract.md | 386 ++++ specs/003-init-command/data-model.md | 291 +++ specs/003-init-command/plan.md | 143 ++ specs/003-init-command/quickstart.md | 470 +++++ specs/003-init-command/research.md | 293 +++ specs/003-init-command/spec.md | 130 ++ specs/003-init-command/tasks.md | 325 ++++ .../checklists/requirements.md | 62 + specs/004-add-command/plan.md | 345 ++++ specs/004-add-command/spec.md | 210 +++ specs/004-add-command/tasks.md | 353 ++++ .../checklists/requirements.md | 69 + .../contracts/update-command-contract.md | 383 ++++ specs/005-update-command/data-model.md | 287 +++ specs/005-update-command/plan.md | 213 +++ specs/005-update-command/quickstart.md | 461 +++++ specs/005-update-command/research.md | 251 +++ specs/005-update-command/spec.md | 153 ++ specs/005-update-command/tasks.md | 377 ++++ .../checklists/requirements.md | 60 + .../contracts/command-contract.md | 413 +++++ specs/006-remove-command/data-model.md | 320 ++++ specs/006-remove-command/plan.md | 146 ++ specs/006-remove-command/quickstart.md | 500 ++++++ specs/006-remove-command/research.md | 210 +++ specs/006-remove-command/spec.md | 163 ++ specs/006-remove-command/tasks.md | 314 ++++ .../checklists/requirements.md | 68 + .../contracts/add-command.md | 271 +++ .../contracts/remove-command.md | 219 +++ .../contracts/update-command.md | 237 +++ .../007-case-insensitive-names/data-model.md | 333 ++++ specs/007-case-insensitive-names/plan.md | 185 ++ .../007-case-insensitive-names/quickstart.md | 265 +++ specs/007-case-insensitive-names/research.md | 294 +++ specs/007-case-insensitive-names/spec.md | 197 ++ specs/007-case-insensitive-names/tasks.md | 322 ++++ .../checklists/requirements.md | 69 + .../contracts/extract-command-contract.md | 535 ++++++ specs/008-extract-command/data-model.md | 383 ++++ specs/008-extract-command/plan.md | 273 +++ specs/008-extract-command/quickstart.md | 713 ++++++++ specs/008-extract-command/research.md | 372 ++++ specs/008-extract-command/spec.md | 200 +++ specs/008-extract-command/tasks.md | 473 +++++ subtree.yaml | 1 - 204 files changed, 32069 insertions(+), 8803 deletions(-) create mode 100644 .windsurf/rules/architecture.md create mode 100644 .windsurf/rules/bootstrap.md create mode 100644 .windsurf/rules/ci-cd.md create mode 100644 .windsurf/rules/compliance-check.md delete mode 100644 .windsurf/workflows/analyze.md delete mode 100644 .windsurf/workflows/implement.md delete mode 100644 .windsurf/workflows/plan.md delete mode 100644 .windsurf/workflows/specify.md create mode 100644 .windsurf/workflows/speckit.analyze.md create mode 100644 .windsurf/workflows/speckit.checklist.md rename .windsurf/workflows/{clarify.md => speckit.clarify.md} (61%) rename .windsurf/workflows/{constitution.md => speckit.constitution.md} (92%) create mode 100644 .windsurf/workflows/speckit.implement.md create mode 100644 .windsurf/workflows/speckit.plan.md create mode 100644 .windsurf/workflows/speckit.roadmap.md create mode 100644 .windsurf/workflows/speckit.specify.md create mode 100644 .windsurf/workflows/speckit.tasks.md delete mode 100644 .windsurf/workflows/tasks.md delete mode 100644 Sources/Subtree/Commands/AddCommand.swift delete mode 100644 Sources/Subtree/Commands/ExtractCommand.swift delete mode 100644 Sources/Subtree/Commands/InitCommand.swift delete mode 100644 Sources/Subtree/Commands/RemoveCommand.swift delete mode 100644 Sources/Subtree/Commands/SubtreeCLI.swift delete mode 100644 Sources/Subtree/Commands/UpdateCommand.swift delete mode 100644 Sources/Subtree/Commands/ValidateCommand.swift delete mode 100644 Sources/Subtree/Git/GitPlumbing.swift delete mode 100644 Sources/Subtree/IO/ConfigIO.swift delete mode 100644 Sources/Subtree/Models/CopyMapping.swift delete mode 100644 Sources/Subtree/Models/SubtreeConfig.swift delete mode 100644 Sources/Subtree/Models/SubtreeEntry.swift delete mode 100644 Sources/Subtree/Models/SubtreeError.swift delete mode 100644 Sources/Subtree/Models/UpdatePolicy.swift delete mode 100644 Sources/Subtree/Utilities/CommitMessageBuilder.swift delete mode 100644 Sources/Subtree/Utilities/RemoteURLParser.swift delete mode 100644 Sources/Subtree/main.swift create mode 100644 Sources/SubtreeLib/Commands/AddCommand.swift create mode 100644 Sources/SubtreeLib/Commands/ExtractCommand.swift create mode 100644 Sources/SubtreeLib/Commands/InitCommand.swift create mode 100644 Sources/SubtreeLib/Commands/RemoveCommand.swift create mode 100644 Sources/SubtreeLib/Commands/SubtreeCommand.swift create mode 100644 Sources/SubtreeLib/Commands/UpdateCommand.swift create mode 100644 Sources/SubtreeLib/Commands/ValidateCommand.swift create mode 100644 Sources/SubtreeLib/Configuration/ExtractionMapping.swift create mode 100644 Sources/SubtreeLib/Configuration/Models/ExtractPattern.swift create mode 100644 Sources/SubtreeLib/Configuration/Models/SubtreeConfiguration.swift create mode 100644 Sources/SubtreeLib/Configuration/Models/SubtreeEntry.swift create mode 100644 Sources/SubtreeLib/Configuration/Parsing/ConfigurationParser.swift create mode 100644 Sources/SubtreeLib/Configuration/Parsing/YAMLErrorTranslator.swift create mode 100644 Sources/SubtreeLib/Configuration/Patterns/GlobPatternValidator.swift create mode 100644 Sources/SubtreeLib/Configuration/Validation/ConfigurationValidator.swift create mode 100644 Sources/SubtreeLib/Configuration/Validation/FormatValidator.swift create mode 100644 Sources/SubtreeLib/Configuration/Validation/LogicValidator.swift create mode 100644 Sources/SubtreeLib/Configuration/Validation/SchemaValidator.swift create mode 100644 Sources/SubtreeLib/Configuration/Validation/TypeValidator.swift create mode 100644 Sources/SubtreeLib/Configuration/Validation/ValidationError.swift create mode 100644 Sources/SubtreeLib/Utilities/CommitMessageFormatter.swift create mode 100644 Sources/SubtreeLib/Utilities/ConfigFileManager.swift create mode 100644 Sources/SubtreeLib/Utilities/ExitCode.swift create mode 100644 Sources/SubtreeLib/Utilities/GitOperations.swift create mode 100644 Sources/SubtreeLib/Utilities/GlobMatcher.swift create mode 100644 Sources/SubtreeLib/Utilities/NameSanitizer.swift create mode 100644 Sources/SubtreeLib/Utilities/NameValidator.swift create mode 100644 Sources/SubtreeLib/Utilities/PathValidator.swift create mode 100644 Sources/SubtreeLib/Utilities/StringExtensions.swift create mode 100644 Sources/SubtreeLib/Utilities/SubtreeValidationError.swift create mode 100644 Sources/SubtreeLib/Utilities/URLParser.swift create mode 100644 Sources/subtree/EntryPoint.swift delete mode 100644 Tests/IntegrationTests/Add/AddOverrideTests.swift delete mode 100644 Tests/IntegrationTests/Add/AddSmartDefaultsTests.swift delete mode 100644 Tests/IntegrationTests/Add/AddTests.swift create mode 100644 Tests/IntegrationTests/AddIntegrationTests.swift delete mode 100644 Tests/IntegrationTests/Config/ConfigUpdateTests.swift delete mode 100644 Tests/IntegrationTests/Copy/CopyAdvancedTests.swift delete mode 100644 Tests/IntegrationTests/Copy/CopyTests.swift create mode 100644 Tests/IntegrationTests/ExtractIntegrationTests.swift delete mode 100644 Tests/IntegrationTests/Git/GitValidationTests.swift create mode 100644 Tests/IntegrationTests/GitFixtureTests.swift create mode 100644 Tests/IntegrationTests/GitRepositoryFixture.swift delete mode 100644 Tests/IntegrationTests/Init/InitExtensionsTests.swift delete mode 100644 Tests/IntegrationTests/Init/InitTests.swift create mode 100644 Tests/IntegrationTests/InitCommandIntegrationTests.swift delete mode 100644 Tests/IntegrationTests/Remove/RemoveEnhancedTests.swift delete mode 100644 Tests/IntegrationTests/Remove/RemoveTests.swift create mode 100644 Tests/IntegrationTests/RemoveIntegrationTests.swift create mode 100644 Tests/IntegrationTests/SubtreeIntegrationTests.swift create mode 100644 Tests/IntegrationTests/TestHarness.swift delete mode 100644 Tests/IntegrationTests/TestUtils/RepoFixture.swift delete mode 100644 Tests/IntegrationTests/TestUtils/SubprocessHelpers.swift delete mode 100644 Tests/IntegrationTests/Update/UpdateAdvancedTests.swift delete mode 100644 Tests/IntegrationTests/Update/UpdateApplyTests.swift delete mode 100644 Tests/IntegrationTests/Update/UpdateBasicTests.swift delete mode 100644 Tests/IntegrationTests/Update/UpdateBranchTests.swift delete mode 100644 Tests/IntegrationTests/Update/UpdateNetworkTests.swift delete mode 100644 Tests/IntegrationTests/Update/UpdateOverrideTests.swift delete mode 100644 Tests/IntegrationTests/Update/UpdateReportTests.swift delete mode 100644 Tests/IntegrationTests/Update/UpdateSafetyTests.swift create mode 100644 Tests/IntegrationTests/UpdateCommandIntegrationTests.swift delete mode 100644 Tests/IntegrationTests/Utilities/CommitMessageBuilderTests.swift delete mode 100644 Tests/IntegrationTests/Utilities/RemoteURLParserTests.swift delete mode 100644 Tests/IntegrationTests/Verify/VerifyTests.swift create mode 100644 Tests/SubtreeLibTests/CommandTests.swift create mode 100644 Tests/SubtreeLibTests/Commands/AddCommandTests.swift create mode 100644 Tests/SubtreeLibTests/Commands/ExtractCommandTests.swift create mode 100644 Tests/SubtreeLibTests/Commands/RemoveCommandTests.swift create mode 100644 Tests/SubtreeLibTests/ConfigFileManagerTests.swift create mode 100644 Tests/SubtreeLibTests/ConfigurationTests/ConfigValidationIntegrationTests.swift create mode 100644 Tests/SubtreeLibTests/ConfigurationTests/ExtractionMappingTests.swift create mode 100644 Tests/SubtreeLibTests/ConfigurationTests/Models/ExtractPatternTests.swift create mode 100644 Tests/SubtreeLibTests/ConfigurationTests/Models/SubtreeConfigurationTests.swift create mode 100644 Tests/SubtreeLibTests/ConfigurationTests/Models/SubtreeEntryTests.swift create mode 100644 Tests/SubtreeLibTests/ConfigurationTests/Parsing/ConfigurationParserTests.swift create mode 100644 Tests/SubtreeLibTests/ConfigurationTests/Parsing/YAMLErrorTranslatorTests.swift create mode 100644 Tests/SubtreeLibTests/ConfigurationTests/Patterns/GlobPatternValidatorTests.swift create mode 100644 Tests/SubtreeLibTests/ConfigurationTests/SubtreeConfigurationValidationTests.swift create mode 100644 Tests/SubtreeLibTests/ConfigurationTests/Validation/FormatValidatorTests.swift create mode 100644 Tests/SubtreeLibTests/ConfigurationTests/Validation/LogicValidatorTests.swift create mode 100644 Tests/SubtreeLibTests/ConfigurationTests/Validation/SchemaValidatorTests.swift create mode 100644 Tests/SubtreeLibTests/ConfigurationTests/Validation/TypeValidatorTests.swift create mode 100644 Tests/SubtreeLibTests/ConfigurationTests/Validation/ValidationErrorTests.swift create mode 100644 Tests/SubtreeLibTests/ExitCodeTests.swift create mode 100644 Tests/SubtreeLibTests/GitOperationsTests.swift create mode 100644 Tests/SubtreeLibTests/Utilities/CommitMessageFormatterTests.swift create mode 100644 Tests/SubtreeLibTests/Utilities/GlobMatcherTests.swift create mode 100644 Tests/SubtreeLibTests/Utilities/NameSanitizerTests.swift create mode 100644 Tests/SubtreeLibTests/Utilities/NameValidatorTests.swift create mode 100644 Tests/SubtreeLibTests/Utilities/PathValidatorTests.swift create mode 100644 Tests/SubtreeLibTests/Utilities/StringExtensionsTests.swift create mode 100644 Tests/SubtreeLibTests/Utilities/SubtreeValidationErrorTests.swift create mode 100644 Tests/SubtreeLibTests/Utilities/URLParserTests.swift delete mode 100644 Tests/SubtreeTests/Utilities/CommitMessageBuilderTests.swift delete mode 100644 Tests/SubtreeTests/Utilities/RemoteURLParserTests.swift create mode 100644 agents.md create mode 100644 specs/001-cli-bootstrap/checklists/requirements.md create mode 100644 specs/001-cli-bootstrap/contracts/cli-commands.md create mode 100644 specs/001-cli-bootstrap/data-model.md create mode 100644 specs/001-cli-bootstrap/plan.md create mode 100644 specs/001-cli-bootstrap/quickstart.md create mode 100644 specs/001-cli-bootstrap/research.md create mode 100644 specs/001-cli-bootstrap/spec.md create mode 100644 specs/001-cli-bootstrap/tasks.md delete mode 100644 specs/001-i-am-building/contracts/cli-commands.md delete mode 100644 specs/001-i-am-building/data-model.md delete mode 100644 specs/001-i-am-building/plan.md delete mode 100644 specs/001-i-am-building/quickstart.md delete mode 100644 specs/001-i-am-building/research.md delete mode 100644 specs/001-i-am-building/spec.md delete mode 100644 specs/001-i-am-building/tasks.md create mode 100644 specs/002-config-schema-validation/checklists/requirements.md create mode 100644 specs/002-config-schema-validation/contracts/validation-error-format.md create mode 100644 specs/002-config-schema-validation/contracts/yaml-schema.md create mode 100644 specs/002-config-schema-validation/data-model.md create mode 100644 specs/002-config-schema-validation/plan.md create mode 100644 specs/002-config-schema-validation/quickstart.md create mode 100644 specs/002-config-schema-validation/research.md create mode 100644 specs/002-config-schema-validation/spec.md create mode 100644 specs/002-config-schema-validation/tasks.md create mode 100644 specs/003-init-command/checklists/requirements.md create mode 100644 specs/003-init-command/contracts/cli-contract.md create mode 100644 specs/003-init-command/data-model.md create mode 100644 specs/003-init-command/plan.md create mode 100644 specs/003-init-command/quickstart.md create mode 100644 specs/003-init-command/research.md create mode 100644 specs/003-init-command/spec.md create mode 100644 specs/003-init-command/tasks.md create mode 100644 specs/004-add-command/checklists/requirements.md create mode 100644 specs/004-add-command/plan.md create mode 100644 specs/004-add-command/spec.md create mode 100644 specs/004-add-command/tasks.md create mode 100644 specs/005-update-command/checklists/requirements.md create mode 100644 specs/005-update-command/contracts/update-command-contract.md create mode 100644 specs/005-update-command/data-model.md create mode 100644 specs/005-update-command/plan.md create mode 100644 specs/005-update-command/quickstart.md create mode 100644 specs/005-update-command/research.md create mode 100644 specs/005-update-command/spec.md create mode 100644 specs/005-update-command/tasks.md create mode 100644 specs/006-remove-command/checklists/requirements.md create mode 100644 specs/006-remove-command/contracts/command-contract.md create mode 100644 specs/006-remove-command/data-model.md create mode 100644 specs/006-remove-command/plan.md create mode 100644 specs/006-remove-command/quickstart.md create mode 100644 specs/006-remove-command/research.md create mode 100644 specs/006-remove-command/spec.md create mode 100644 specs/006-remove-command/tasks.md create mode 100644 specs/007-case-insensitive-names/checklists/requirements.md create mode 100644 specs/007-case-insensitive-names/contracts/add-command.md create mode 100644 specs/007-case-insensitive-names/contracts/remove-command.md create mode 100644 specs/007-case-insensitive-names/contracts/update-command.md create mode 100644 specs/007-case-insensitive-names/data-model.md create mode 100644 specs/007-case-insensitive-names/plan.md create mode 100644 specs/007-case-insensitive-names/quickstart.md create mode 100644 specs/007-case-insensitive-names/research.md create mode 100644 specs/007-case-insensitive-names/spec.md create mode 100644 specs/007-case-insensitive-names/tasks.md create mode 100644 specs/008-extract-command/checklists/requirements.md create mode 100644 specs/008-extract-command/contracts/extract-command-contract.md create mode 100644 specs/008-extract-command/data-model.md create mode 100644 specs/008-extract-command/plan.md create mode 100644 specs/008-extract-command/quickstart.md create mode 100644 specs/008-extract-command/research.md create mode 100644 specs/008-extract-command/spec.md create mode 100644 specs/008-extract-command/tasks.md delete mode 100644 subtree.yaml diff --git a/.windsurf/rules/architecture.md b/.windsurf/rules/architecture.md new file mode 100644 index 0000000..7eef89a --- /dev/null +++ b/.windsurf/rules/architecture.md @@ -0,0 +1,193 @@ +--- +trigger: always_on +--- + +# Subtree CLI - Architecture & Testing Patterns + +Last Updated: 2025-10-26 | Phase: 10 (Complete) | Context: Proven patterns from MVP + CI implementation + +## Architecture Pattern: Library + Executable + +**Pattern**: Swift community standard for CLI tools + +### Structure + +``` +Sources/ +├── SubtreeLib/ # Library module (all business logic) +│ ├── Commands/ # Command implementations +│ └── Utilities/ # Helper utilities +└── subtree/ # Executable module (thin wrapper) + └── EntryPoint.swift # Calls SubtreeCommand.main() +``` + +### Responsibilities + +**SubtreeLib (Library)**: +- Contains ALL business logic +- Fully unit-testable with `@testable import` +- Can be used programmatically by other Swift code +- Exports `SubtreeCommand` as public API + +**subtree (Executable)**: +- Thin wrapper (5 lines) +- Single responsibility: Call `SubtreeCommand.main()` +- No business logic +- Enables standalone CLI usage + +### Benefits + +✅ **Testability**: Unit tests import SubtreeLib directly +✅ **Reusability**: Library can be embedded in other tools +✅ **Separation**: CLI concerns separate from business logic +✅ **Standard**: Matches swift-argument-parser best practices + +## Command Pattern: ArgumentParser + +**Framework**: swift-argument-parser 1.6.1 + +### Key Conventions + +- **Public struct**: Conforming to `ParsableCommand` +- **Static configuration**: Defines command metadata +- **Subcommands array**: Lists available subcommands +- **Public init**: Required for library usage +- **Version string**: Displayed with `--version` + +### Automatic Features + +ArgumentParser provides for free: +- `--help` / `-h` flag +- `--version` flag +- Subcommand help (`subtree --help`) +- Error handling with usage display +- Bash completion support + +## Testing Pattern: Two-Layer Approach + +### Unit Tests (SubtreeLibTests/) + +**Purpose**: Test business logic directly + +**Characteristics**: +- Uses `@testable import` for internal access +- Tests configuration, logic, utilities +- Fast (no process execution) +- Built-in Swift Testing framework (Swift 6.1) + +### Integration Tests (IntegrationTests/) + +**Purpose**: Test CLI end-to-end + +**Characteristics**: +- Uses TestHarness to execute actual binary +- Captures stdout/stderr/exit code +- Tests real CLI behavior +- Async execution with swift-subprocess + +## TestHarness Pattern + +**Location**: `Tests/IntegrationTests/TestHarness.swift` + +### Purpose + +Execute CLI commands in tests and capture results. + +### Core API + +```swift +struct TestHarness { + func run(arguments: [String]) async throws -> CommandResult +} + +struct CommandResult { + let stdout: String + let stderr: String + let exitCode: Int +} +``` + +### Git Support + +**GitRepositoryFixture**: Creates temporary git repositories for testing +- UUID-based unique paths (parallel-safe) +- Async initialization with initial commit +- Helper methods: `getCurrentCommit()`, `getCommitCount()`, `fileExists()` +- Complete cleanup with `tearDown()` + +**TestHarness Git Helpers**: `runGit()`, `verifyCommitExists()`, `getGitConfig()`, `isGitRepository()` + +## Swift Testing Framework + +**Version**: Built into Swift 6.1 toolchain (no package dependency) + +### Key Features + +- **@Suite**: Groups related tests +- **@Test**: Marks individual test functions +- **#expect**: Assertion macro (replaces XCTest assertions) +- **async/await**: First-class async test support +- **Parallel execution**: Tests run concurrently by default + +## Conventions + +### Swift Naming + +- **Files**: PascalCase (SubtreeCommand.swift, ExitCode.swift) +- **Types**: PascalCase (SubtreeCommand, TestHarness) +- **Functions**: camelCase (run, verifyCommitExists) +- **Constants**: camelCase (executablePath, exitCode) + +### Testing Discipline + +- **TDD**: Write tests first, verify failure, implement, verify pass +- **Test naming**: Descriptive strings in @Test("description") +- **Async tests**: Use async/await, not callbacks +- **Test isolation**: Each test is independent, use fixtures for setup +- **Assertions**: Use #expect(), not traditional assert() + +### Code Organization + +- **Library first**: All logic in SubtreeLib +- **Public API**: Only expose what's needed externally +- **Documentation**: Use Swift doc comments (///) +- **Error handling**: Use Swift errors, not exit() in library code + +--- + +## MVP Validation Checkpoint + +Verify architecture matches implementation: + +```bash +# 1. Library + Executable Pattern +ls -la Sources/SubtreeLib/Commands/ +wc -l Sources/subtree/main.swift # Should be ~5 lines + +# 2. Test Structure +grep "@testable import SubtreeLib" Tests/SubtreeLibTests/*.swift +grep "let harness: TestHarness" Tests/IntegrationTests/*.swift + +# 3. Swift Testing (no package dependency) +! grep "swift-testing" Package.swift || echo "ERROR" + +# 4. All tests pass +swift test # Should show 25/25 tests passed +``` + +**Expected**: All checks pass, architecture is consistent + +--- + +## Update Triggers + +Update this file when: + +1. **Architecture patterns change** (new layers, different structure) +2. **Testing patterns evolve** (new test utilities, different approaches) +3. **Framework updates** (ArgumentParser API changes, Testing updates) +4. **New command patterns** (subcommands, shared utilities) + +--- + +**Lines**: ~195 (under 200-line limit) \ No newline at end of file diff --git a/.windsurf/rules/bootstrap.md b/.windsurf/rules/bootstrap.md new file mode 100644 index 0000000..2fce398 --- /dev/null +++ b/.windsurf/rules/bootstrap.md @@ -0,0 +1,120 @@ +--- +trigger: always_on +--- + +# Subtree CLI - Bootstrap Rules + +Last Updated: 2025-10-26 | Spec: 001-cli-bootstrap | Phase: 10 (Complete) + +## Dependencies + +**Purpose**: Swift 6.1 CLI tool for managing git subtrees with declarative configuration + +- **swift-argument-parser 1.6.1**: CLI argument parsing +- **Yams 6.1.0**: YAML configuration parsing +- **swift-subprocess 0.1.0+**: Process execution +- **swift-system 1.5.0**: File operations (Ubuntu 20.04 compatible) + +## Structure + +``` +Sources/SubtreeLib/ # Library (all business logic) +├── Commands/ # ArgumentParser commands +└── Utilities/ # Helpers (ExitCode, etc.) +Sources/subtree/ # Executable (calls SubtreeLib.main()) +Tests/SubtreeLibTests/ # Unit tests (@testable import) +Tests/IntegrationTests/ # Integration tests (run binary + git fixtures) +``` + +**Platforms**: macOS 13+, Ubuntu 20.04 LTS + +## Architecture + +**Library + Executable** (Swift standard pattern) +- SubtreeLib: All logic, fully testable +- subtree: Thin wrapper +- Rationale: Testability + future programmatic use + +## CI/CD + +**Status**: Complete (Phase 5: local act, Phase 9: GitHub Actions) +**Details**: See [ci-cd.md](./ci-cd.md) for workflows, platform matrix, and validation + +## Features (Complete) + +**CLI Skeleton**: +- 6 stub commands (init, add, update, remove, extract, validate) +- Help system (`subtree --help`) +- Exit codes (0=success, non-zero=error) + +**Test Infrastructure**: +- TestHarness (CLI execution with swift-subprocess) +- GitRepositoryFixture (temporary git repos with UUID-based paths) +- 25 tests total (2 command + 7 exit code + 16 integration) + +**CI Automation**: +- GitHub Actions (macOS-15 + Ubuntu 20.04) +- Local testing (nektos/act with ci-local.yml) +- Platform-specific Swift setup (DEVELOPER_DIR vs setup-swift) + +--- + +## Update Triggers + +Agent MUST update when changes occur to: +1. **Project dependencies** - Add/remove packages, version changes +2. **Directory structure** - New folders, renamed paths +3. **Architecture patterns** - New layers, different structure +4. **CI/CD pipeline** - Workflow changes, platform updates +5. **Major feature areas** - New commands, test utilities + +**Procedure**: Read current file → identify changes → update surgically → keep <200 lines + +--- + +## Rules Organization + +**Pattern**: Multiple specialized files (not monolithic) + +**Current Files**: +- `compliance-check.md`: Constitution checks (always-on) +- `bootstrap.md`: Bootstrap context (this file) +- `architecture.md`: Architecture & testing patterns +- `ci-cd.md`: CI/CD workflows & validation + +**Rationale**: Modular (<200 lines each), focused, scalable + +--- + +## agents.md Maintenance + +**File**: `/agents.md` (universal AI onboarding per https://agents.md/) + +**Purpose**: High-level context for ANY AI tool + +**Update**: After EVERY phase (sync with README.md) + +**Procedure**: +1. Update header (date, phase) +2. Update status (✅ exists, ⏳ doesn't) +3. Update next phase pointer + +**See**: [agents.md](../agents.md) for current state + +--- + +## Architecture & Testing Patterns + +**Detailed Documentation**: See [architecture.md](./architecture.md) + +**Quick Reference**: +- Library + Executable pattern (SubtreeLib + subtree) +- ArgumentParser for commands +- Two-layer testing (unit + integration) +- TestHarness for CLI execution +- Swift Testing (built into Swift 6.1) + +--- + +**Lines**: ~120 (well under 200-line limit) + diff --git a/.windsurf/rules/ci-cd.md b/.windsurf/rules/ci-cd.md new file mode 100644 index 0000000..82554c8 --- /dev/null +++ b/.windsurf/rules/ci-cd.md @@ -0,0 +1,115 @@ +--- +trigger: always_on +--- + +# Subtree CLI - CI/CD & Validation + +Last Updated: 2025-10-26 | Phase: 10 (Complete) | Context: Production CI pipeline + +## CI/CD Pipeline + +**Platform**: GitHub Actions with local testing via nektos/act + +### Workflow: ci.yml + +**Purpose**: Production CI for all pushes and pull requests + +**Platform Matrix**: +- macOS-15 (Xcode 16.4 = Swift 6.1) +- Ubuntu 20.04 LTS (Swift 6.1) + +**Swift Setup Strategy**: +- **macOS**: Native Xcode via `DEVELOPER_DIR=/Applications/Xcode_16.4.app/Contents/Developer` + - No download/setup needed + - Faster execution + - Pre-installed on GitHub runners +- **Ubuntu**: `swift-actions/setup-swift@v2` + - Downloads Swift 6.1 + - Required (no Swift on Ubuntu runners) + +**Steps**: +1. Checkout code (`actions/checkout@v4`) +2. Setup Swift (Ubuntu only, conditional) +3. Verify Swift version +4. Build (`swift build`) +5. Run tests (`swift test` with 10-minute timeout) + +**Triggers**: +- Push to `main` or `001-cli-bootstrap` branches +- Pull requests to `main` + +### Workflow: ci-local.yml + +**Purpose**: Local CI testing with nektos/act + +**Platform**: Ubuntu only (Docker container) + +**Container**: `swift:6.1` (Swift pre-installed) + +**Usage**: +```bash +# Run local CI validation +act workflow_dispatch -W .github/workflows/ci-local.yml +``` + +**When to Use**: +- Before committing changes +- Testing workflow modifications +- Verifying test coverage + +**Limitations**: +- Linux only (act can't run macOS containers) +- Uses Docker (requires Docker running) +- First run downloads ~1.5GB image + +## CI Complete Validation Checkpoint + +Run these checks to verify CI matches implementation: + +### 1. Verify Workflow Configuration + +```bash +# Check ci.yml has correct platform matrix +grep "macos-15" .github/workflows/ci.yml +grep "ubuntu-20.04" .github/workflows/ci.yml + +# Verify DEVELOPER_DIR for macOS +grep "DEVELOPER_DIR" .github/workflows/ci.yml + +# Check conditional setup-swift for Ubuntu +grep "if: matrix.os == 'ubuntu-20.04'" .github/workflows/ci.yml +``` + +### 2. Verify Local CI Works + +```bash +# Test with act (should pass) +act workflow_dispatch -W .github/workflows/ci-local.yml + +# All 25 tests should pass in container +``` + +### 3. Verify Test Coverage + +```bash +# Check all test suites run +swift test 2>&1 | grep "Suite" + +# Should show: +# - Command Tests (2 tests) +# - Exit Code Tests (7 tests) +# - Subtree Integration Tests (9 tests) +# - Git Fixture Tests (7 tests) +# Total: 25 tests +``` + +### 4. Verify CI Badge + +Check README.md contains CI badge linking to workflow. + +**Expected**: All checks pass, CI pipeline matches documentation + +--- + +**Lines**: ~100 (well under 200-line limit) + diff --git a/.windsurf/rules/compliance-check.md b/.windsurf/rules/compliance-check.md new file mode 100644 index 0000000..92a9105 --- /dev/null +++ b/.windsurf/rules/compliance-check.md @@ -0,0 +1,5 @@ +--- +trigger: always_on +--- + +Before starting any feature work or behavior change, read .specify/memory/constitution.md and verify your approach complies with all five core principles (spec-first, TDD, small independent specs, CI gates, agent maintenance). After completing feature work, verify final compliance and check if .windsurf/rules updates are needed per Principle V triggers. \ No newline at end of file diff --git a/.windsurf/workflows/analyze.md b/.windsurf/workflows/analyze.md deleted file mode 100644 index f4c1a7b..0000000 --- a/.windsurf/workflows/analyze.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation. ---- - -The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty). - -User input: - -$ARGUMENTS - -Goal: Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/tasks` has successfully produced a complete `tasks.md`. - -STRICTLY READ-ONLY: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually). - -Constitution Authority: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/analyze`. - -Execution steps: - -1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths: - - SPEC = FEATURE_DIR/spec.md - - PLAN = FEATURE_DIR/plan.md - - TASKS = FEATURE_DIR/tasks.md - Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command). - -2. Load artifacts: - - Parse spec.md sections: Overview/Context, Functional Requirements, Non-Functional Requirements, User Stories, Edge Cases (if present). - - Parse plan.md: Architecture/stack choices, Data Model references, Phases, Technical constraints. - - Parse tasks.md: Task IDs, descriptions, phase grouping, parallel markers [P], referenced file paths. - - Load constitution `.specify/memory/constitution.md` for principle validation. - -3. Build internal semantic models: - - Requirements inventory: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" -> `user-can-upload-file`). - - User story/action inventory. - - Task coverage mapping: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases). - - Constitution rule set: Extract principle names and any MUST/SHOULD normative statements. - -4. Detection passes: - A. Duplication detection: - - Identify near-duplicate requirements. Mark lower-quality phrasing for consolidation. - B. Ambiguity detection: - - Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria. - - Flag unresolved placeholders (TODO, TKTK, ???, , etc.). - C. Underspecification: - - Requirements with verbs but missing object or measurable outcome. - - User stories missing acceptance criteria alignment. - - Tasks referencing files or components not defined in spec/plan. - D. Constitution alignment: - - Any requirement or plan element conflicting with a MUST principle. - - Missing mandated sections or quality gates from constitution. - E. Coverage gaps: - - Requirements with zero associated tasks. - - Tasks with no mapped requirement/story. - - Non-functional requirements not reflected in tasks (e.g., performance, security). - F. Inconsistency: - - Terminology drift (same concept named differently across files). - - Data entities referenced in plan but absent in spec (or vice versa). - - Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note). - - Conflicting requirements (e.g., one requires to use Next.js while other says to use Vue as the framework). - -5. Severity assignment heuristic: - - CRITICAL: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality. - - HIGH: Duplicate or conflicting requirement, ambiguous security/performance attribute, 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: $ARGUMENTS diff --git a/.windsurf/workflows/implement.md b/.windsurf/workflows/implement.md deleted file mode 100644 index 003dce9..0000000 --- a/.windsurf/workflows/implement.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -description: Execute the implementation plan by processing and executing all tasks defined in tasks.md ---- - -The user input 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 - -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. - -2. 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 - - **IF EXISTS**: Read contracts/ for API specifications and test requirements - - **IF EXISTS**: Read research.md for technical decisions and constraints - - **IF EXISTS**: Read quickstart.md for integration scenarios - -3. 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 - -4. 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 - - **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 - -5. 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 - - **Integration work**: Database connections, middleware, logging, external services - - **Polish and validation**: Unit tests, performance optimization, documentation - -6. 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 - - Provide clear error messages with context for debugging - - Suggest next steps if implementation cannot proceed - - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file. - -7. Completion validation: - - Verify all required tasks are completed - - Check that implemented features match the original specification - - Validate that tests pass and coverage meets requirements - - Confirm the implementation follows the technical plan - - Report final status with summary of completed work - -Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/tasks` first to regenerate the task list. diff --git a/.windsurf/workflows/plan.md b/.windsurf/workflows/plan.md deleted file mode 100644 index 23c020a..0000000 --- a/.windsurf/workflows/plan.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -description: Execute the implementation planning workflow using the plan template to generate design artifacts. ---- - -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 - -Given the implementation details provided as an argument, do this: - -1. Run `.specify/scripts/bash/setup-plan.sh --json` from the repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. All future file paths must be absolute. - - BEFORE proceeding, inspect FEATURE_SPEC for a `## Clarifications` section with at least one `Session` subheading. If missing or clearly ambiguous areas remain (vague adjectives, unresolved critical choices), PAUSE and instruct the user to run `/clarify` first to reduce rework. Only continue if: (a) Clarifications exist OR (b) an explicit user override is provided (e.g., "proceed without clarification"). Do not attempt to fabricate clarifications yourself. -2. Read and analyze the feature specification to understand: - - The feature requirements and user stories - - Functional and non-functional requirements - - Success criteria and acceptance criteria - - Any technical constraints or dependencies mentioned - -3. Read the constitution at `.specify/memory/constitution.md` to understand constitutional requirements. - -4. Execute the implementation plan template: - - Load `.specify/templates/plan-template.md` (already copied to IMPL_PLAN path) - - Set Input path to FEATURE_SPEC - - Run the Execution Flow (main) function steps 1-9 - - The template is self-contained and executable - - Follow error handling and gate checks as specified - - Let the template guide artifact generation in $SPECS_DIR: - * Phase 0 generates research.md - * Phase 1 generates data-model.md, contracts/, quickstart.md - * Phase 2 generates tasks.md - - Incorporate user-provided details from arguments into Technical Context: $ARGUMENTS - - Update Progress Tracking as you complete each phase - -5. Verify execution completed: - - Check Progress Tracking shows all phases complete - - Ensure all required artifacts were generated - - Confirm no ERROR states in execution - -6. Report results with branch name, file paths, and generated artifacts. - -Use absolute paths with the repository root for all file operations to avoid path issues. diff --git a/.windsurf/workflows/specify.md b/.windsurf/workflows/specify.md deleted file mode 100644 index 0f92105..0000000 --- a/.windsurf/workflows/specify.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -description: Create or update the feature specification from a natural language feature description. ---- - -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 - -The text the user typed after `/specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `$ARGUMENTS` appears literally below. Do not ask the user to repeat it unless they provided an empty command. - -Given that feature description, do this: - -1. Run the script `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"` from repo root and parse its JSON output for BRANCH_NAME and SPEC_FILE. All file paths must be absolute. - **IMPORTANT** You must only ever run this script once. The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for. -2. Load `.specify/templates/spec-template.md` to understand required sections. -3. 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. -4. Report completion with branch name, spec file path, and readiness for the next phase. - -Note: The script creates and checks out the new branch and initializes the spec file before writing. diff --git a/.windsurf/workflows/speckit.analyze.md b/.windsurf/workflows/speckit.analyze.md new file mode 100644 index 0000000..98b04b0 --- /dev/null +++ b/.windsurf/workflows/speckit.analyze.md @@ -0,0 +1,184 @@ +--- +description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation. +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal + +Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.md`. + +## Operating Constraints + +**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually). + +**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`. + +## Execution Steps + +### 1. Initialize Analysis Context + +Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths: + +- SPEC = FEATURE_DIR/spec.md +- PLAN = FEATURE_DIR/plan.md +- TASKS = FEATURE_DIR/tasks.md + +Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command). +For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + +### 2. Load Artifacts (Progressive Disclosure) + +Load only the minimal necessary context from each artifact: + +**From spec.md:** + +- Overview/Context +- Functional Requirements +- Non-Functional Requirements +- User Stories +- Edge Cases (if present) + +**From plan.md:** + +- Architecture/stack choices +- Data Model references +- Phases +- Technical constraints + +**From tasks.md:** + +- Task IDs +- Descriptions +- Phase grouping +- Parallel markers [P] +- Referenced file paths + +**From constitution:** + +- Load `.specify/memory/constitution.md` for principle validation + +### 3. Build Semantic Models + +Create internal representations (do not include raw artifacts in output): + +- **Requirements inventory**: 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**: Discrete user actions with acceptance criteria +- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases) +- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements + +### 4. Detection Passes (Token-Efficient Analysis) + +Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary. + +#### A. Duplication Detection + +- Identify near-duplicate requirements +- Mark lower-quality phrasing for consolidation + +#### B. Ambiguity Detection + +- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria +- Flag unresolved placeholders (TODO, TKTK, ???, ``, 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 Next.js while other specifies Vue) + +### 5. Severity Assignment + +Use this heuristic to prioritize findings: + +- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality +- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion +- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case +- **LOW**: Style/wording improvements, minor redundancy not affecting execution order + +### 6. Produce Compact Analysis Report + +Output a Markdown report (no file writes) with the following structure: + +## Specification Analysis Report + +| ID | Category | Severity | Location(s) | Summary | Recommendation | +|----|----------|----------|-------------|---------|----------------| +| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version | + +(Add one row per finding; generate stable IDs prefixed by category initial.) + +**Coverage Summary Table:** + +| Requirement Key | Has Task? | Task IDs | Notes | +|-----------------|-----------|----------|-------| + +**Constitution Alignment Issues:** (if any) + +**Unmapped Tasks:** (if any) + +**Metrics:** + +- Total Requirements +- Total Tasks +- Coverage % (requirements with >=1 task) +- Ambiguity Count +- Duplication Count +- Critical Issues Count + +### 7. Provide Next Actions + +At end of report, output a concise Next Actions block: + +- If CRITICAL issues exist: Recommend resolving before `/speckit.implement` +- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions +- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'" + +### 8. Offer Remediation + +Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.) + +## Operating Principles + +### Context Efficiency + +- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation +- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis +- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow +- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts + +### Analysis Guidelines + +- **NEVER modify files** (this is read-only analysis) +- **NEVER hallucinate missing sections** (if absent, report them accurately) +- **Prioritize constitution violations** (these are always CRITICAL) +- **Use examples over exhaustive rules** (cite specific instances, not generic patterns) +- **Report zero issues gracefully** (emit success report with coverage statistics) + +## Context + +$ARGUMENTS diff --git a/.windsurf/workflows/speckit.checklist.md b/.windsurf/workflows/speckit.checklist.md new file mode 100644 index 0000000..970e6c9 --- /dev/null +++ b/.windsurf/workflows/speckit.checklist.md @@ -0,0 +1,294 @@ +--- +description: Generate a custom checklist for the current feature based on user requirements. +--- + +## Checklist Purpose: "Unit Tests for English" + +**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain. + +**NOT for verification/testing**: + +- ❌ NOT "Verify the button clicks correctly" +- ❌ NOT "Test error handling works" +- ❌ NOT "Confirm the API returns 200" +- ❌ NOT checking if code/implementation matches the spec + +**FOR requirements quality validation**: + +- ✅ "Are visual hierarchy requirements defined for all card types?" (completeness) +- ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity) +- ✅ "Are hover state requirements consistent across all interactive elements?" (consistency) +- ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage) +- ✅ "Does the spec define what happens when logo image fails to load?" (edge cases) + +**Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works. + +## User Input + +```text +$ARGUMENTS +``` + +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. + - 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. + 4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria. + 5. Formulate questions chosen from these archetypes: + - Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay limited to local module correctness?") + - Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?") + - Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?") + - Audience framing (e.g., "Will this be used by the author only or peers during PR review?") + - Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?") + - 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 + + 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`) + - Format: `[domain].md` + - If file exists, append to existing file + - Number items sequentially starting from CHK001 + - Each `/speckit.checklist` run creates a NEW file (never overwrites existing checklists) + + **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? + - **Measurability**: Can requirements be objectively verified? + - **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?) + - **Acceptance Criteria Quality** (Are success criteria measurable?) + - **Scenario Coverage** (Are all flows/cases addressed?) + - **Edge Case Coverage** (Are boundary conditions defined?) + - **Non-Functional Requirements** (Performance, Security, Accessibility, etc. - are they specified?) + - **Dependencies & Assumptions** (Are they documented and validated?) + - **Ambiguities & Conflicts** (What needs clarification?) + + **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] + - "Are keyboard navigation requirements defined for all interactive UI?" [Coverage] + - "Is the fallback behavior specified when logo image fails to load?" [Edge Cases] + - "Are loading states defined for asynchronous episode data?" [Completeness] + - "Does the spec define visual hierarchy for competing UI elements?" [Clarity] + + **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.] + - Reference spec section `[Spec §X.Y]` when checking existing requirements + - Use `[Gap]` marker when checking for missing requirements + + **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]" + - Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]" + - 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" + - ❌ "Click", "navigate", "render", "load", "execute" + - ❌ Test cases, test plans, QA procedures + - ❌ 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]?" + - ✅ "Can [requirement] be objectively measured/verified?" + - ✅ "Are [edge cases/scenarios] addressed in requirements?" + - ✅ "Does the spec define [missing aspect]?" + +6. **Structure Reference**: Generate the checklist following the canonical template in `.specify/templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### ` lines with globally incrementing IDs starting at CHK001. + +7. **Report**: Output full path to created checklist, item count, and remind user that each run creates a new file. Summarize: + - Focus areas selected + - Depth level + - Actor/timing + - Any explicit user-specified must-have items incorporated + +**Important**: Each `/speckit.checklist` command invocation creates a checklist file using short, descriptive names unless file already exists. This allows: + +- Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`) +- Simple, memorable filenames that indicate checklist purpose +- Easy identification and navigation in the `checklists/` folder + +To avoid clutter, use descriptive types and clean up obsolete checklists when done. + +## Example Checklist Types & Sample Items + +**UX Requirements Quality:** `ux.md` + +Sample items (testing the requirements, NOT the implementation): + +- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]" +- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]" +- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]" +- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]" +- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]" +- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]" + +**API Requirements Quality:** `api.md` + +Sample items: + +- "Are error response formats specified for all failure scenarios? [Completeness]" +- "Are rate limiting requirements quantified with specific thresholds? [Clarity]" +- "Are authentication requirements consistent across all endpoints? [Consistency]" +- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]" +- "Is versioning strategy documented in requirements? [Gap]" + +**Performance Requirements Quality:** `performance.md` + +Sample items: + +- "Are performance requirements quantified with specific metrics? [Clarity]" +- "Are performance targets defined for all critical user journeys? [Coverage]" +- "Are performance requirements under different load conditions specified? [Completeness]" +- "Can performance requirements be objectively measured? [Measurability]" +- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]" + +**Security Requirements Quality:** `security.md` + +Sample items: + +- "Are authentication requirements specified for all protected resources? [Coverage]" +- "Are data protection requirements defined for sensitive information? [Completeness]" +- "Is the threat model documented and requirements aligned to it? [Traceability]" +- "Are security requirements consistent with compliance obligations? [Consistency]" +- "Are security failure/breach response requirements defined? [Gap, Exception Flow]" + +## Anti-Examples: What NOT To Do + +**❌ WRONG - These test implementation, not requirements:** + +```markdown +- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001] +- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003] +- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010] +- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005] +``` + +**✅ CORRECT - These test requirements quality:** + +```markdown +- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001] +- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003] +- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010] +- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005] +- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap] +- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001] +``` + +**Key Differences:** + +- Wrong: Tests if the system works correctly +- Correct: Tests if the requirements are written correctly +- Wrong: Verification of behavior +- Correct: Validation of requirement quality +- Wrong: "Does it do X?" +- Correct: "Is X clearly specified?" diff --git a/.windsurf/workflows/clarify.md b/.windsurf/workflows/speckit.clarify.md similarity index 61% rename from .windsurf/workflows/clarify.md rename to .windsurf/workflows/speckit.clarify.md index 26ff530..8ff62c3 100644 --- a/.windsurf/workflows/clarify.md +++ b/.windsurf/workflows/speckit.clarify.md @@ -2,15 +2,19 @@ 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. --- -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: +## User Input +```text $ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Outline 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. +Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/speckit.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: @@ -18,7 +22,8 @@ Execution steps: - `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. + - If JSON parsing fails, abort and instruct user to re-run `/speckit.specify` or verify feature branch environment. + - 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 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). @@ -77,52 +82,65 @@ Execution steps: - 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. + - Maximum of 10 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. + - 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: + - For multiple‑choice questions: + - **Analyze all options** and determine the **most suitable option** based on: + - Best practices for the project type + - Common patterns in similar implementations + - Risk reduction (security, performance, maintainability) + - Alignment with any explicit project goals or constraints visible in the spec + - Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice). + - Format as: `**Recommended:** Option [X] - ` + - Then render all options as a Markdown table: | Option | Description | |--------|-------------| | A |