specly 0.1.0__tar.gz

specly-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: specly
+Version: 0.1.0
+Summary: Spec-Driven Development scaffolding in Python
+Author: davidops
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: strands
+Requires-Dist: strands-agents>=1.0.0; extra == "strands"
+Provides-Extra: ax
+
+# Specly Python CLI (Local Preview)
+
+Standalone Python distribution for **Specly** — Spec-Driven Development scaffolding without requiring Node.js.
+
+> **Status:** Local development and testing only. This package is **not published** to PyPI or any public registry. The package name and public command identities remain provisional.
+
+## Supported Commands
+
+- `specly init [options]`: Generate SDD files conforming to canonical artifact contract v1.
+- `specly doctor`: Read-only readiness check for Python runtime (>=3.10), agent markers, and packaged template fingerprints.
+- `specly plan <feature>`: Read-only preview of proposed local file writes and effects.
+- `specly verify <feature>`: Read-only verification of local specification files and checklist progress.
+
+*Note: `specly run` and `specly recover` are not supported in the Python CLI and remain available via the Node CLI.*
+
+## Interruption & Overwrite Safety
+
+- Running `init` on existing files checks their SHA-256 against canonical templates.
+- Files matching canonical template bytes are reported as already complete and skipped.
+- Modified or partial files trigger a warning requiring review; they are never overwritten without explicit `--force`.
+
+## Optional Strands Task Execution Adapter
+
+The optional module `specly_cli.optional.strands_adapter` provides a strictly bounded task-execution boundary using the Strands Agents SDK:
+
+- **Disabled by default:** Default commands (`init`, `doctor`, `plan`, `verify`) never import Strands or inspect ambient credentials.
+- **Explicit authorization:** Execution requires an `ExecutionRequest` bound to an affirmative `approval_digest`, explicit provider configuration, and task ID.
+- **Strict safety boundary:**
+  - Allowed tools are restricted to structured, data-only local operations (`write-file`). Shell, subprocess, VCS, PR, and network tools are prohibited.
+  - Writable roots are confined to the project root; directory traversal, symlink escapes, and reserved paths (`.git`, `.specly`) fail closed.
+  - Resource limits (`budget_calls`, `timeout_seconds`) halt execution with a `limited` status and claim no success.
+- **Evidence distinction:** An `ExecutionRecord` documents tool outcomes and status, but **never** marks tasks checked or implies requirements acceptance. Local unit tests run against local mock fixtures and contact no external providers.
+- **Installation:** Optional extra: `pip install "specly[strands]"`.
+
+## Optional Google AX Cluster Adapter
+
+The optional module `specly_cli.optional.ax_adapter` provides read-only prerequisite diagnostics and effect previews for Google AX / Agent Substrate:
+
+- **Disabled by default:** Default commands never import AX or inspect `KUBECONFIG` / ambient cluster credentials.
+- **Offline diagnostics:** Local inspection checks required binaries (`kubectl`, `ko`, `go`) without probing remote clusters or networks.
+- **Immutable effect preview:** Previews bind context, namespace, operation, resource targets, and proposed effects to an immutable SHA-256 approval digest.
+- **Distinct mutation approval:** Submitting a cluster operation requires affirmative approval matching the preview digest and explicit destination authorization (destination, operation, credential/session). Changing targets or effects invalidates approval and fails closed.
+- **Evidence status:** Labeled `unverified` (Google AX prerelease). No live cluster was contacted during local tests.
+- **Installation:** Optional extra: `pip install "specly[ax]"`.
+
+## Development & Testing
+
+```bash
+# Verify asset synchronization against canonical repository sources
+python3 python/scripts/sync_assets.py --check
+
+# Run test suite
+PYTHONPATH=python/src python3 -m unittest discover -s python/tests
+
+# Build isolated wheel
+uv build --wheel --no-sources
+```

specly-0.1.0/README.md

@@ -0,0 +1,57 @@
+# Specly Python CLI (Local Preview)
+
+Standalone Python distribution for **Specly** — Spec-Driven Development scaffolding without requiring Node.js.
+
+> **Status:** Local development and testing only. This package is **not published** to PyPI or any public registry. The package name and public command identities remain provisional.
+
+## Supported Commands
+
+- `specly init [options]`: Generate SDD files conforming to canonical artifact contract v1.
+- `specly doctor`: Read-only readiness check for Python runtime (>=3.10), agent markers, and packaged template fingerprints.
+- `specly plan <feature>`: Read-only preview of proposed local file writes and effects.
+- `specly verify <feature>`: Read-only verification of local specification files and checklist progress.
+
+*Note: `specly run` and `specly recover` are not supported in the Python CLI and remain available via the Node CLI.*
+
+## Interruption & Overwrite Safety
+
+- Running `init` on existing files checks their SHA-256 against canonical templates.
+- Files matching canonical template bytes are reported as already complete and skipped.
+- Modified or partial files trigger a warning requiring review; they are never overwritten without explicit `--force`.
+
+## Optional Strands Task Execution Adapter
+
+The optional module `specly_cli.optional.strands_adapter` provides a strictly bounded task-execution boundary using the Strands Agents SDK:
+
+- **Disabled by default:** Default commands (`init`, `doctor`, `plan`, `verify`) never import Strands or inspect ambient credentials.
+- **Explicit authorization:** Execution requires an `ExecutionRequest` bound to an affirmative `approval_digest`, explicit provider configuration, and task ID.
+- **Strict safety boundary:**
+  - Allowed tools are restricted to structured, data-only local operations (`write-file`). Shell, subprocess, VCS, PR, and network tools are prohibited.
+  - Writable roots are confined to the project root; directory traversal, symlink escapes, and reserved paths (`.git`, `.specly`) fail closed.
+  - Resource limits (`budget_calls`, `timeout_seconds`) halt execution with a `limited` status and claim no success.
+- **Evidence distinction:** An `ExecutionRecord` documents tool outcomes and status, but **never** marks tasks checked or implies requirements acceptance. Local unit tests run against local mock fixtures and contact no external providers.
+- **Installation:** Optional extra: `pip install "specly[strands]"`.
+
+## Optional Google AX Cluster Adapter
+
+The optional module `specly_cli.optional.ax_adapter` provides read-only prerequisite diagnostics and effect previews for Google AX / Agent Substrate:
+
+- **Disabled by default:** Default commands never import AX or inspect `KUBECONFIG` / ambient cluster credentials.
+- **Offline diagnostics:** Local inspection checks required binaries (`kubectl`, `ko`, `go`) without probing remote clusters or networks.
+- **Immutable effect preview:** Previews bind context, namespace, operation, resource targets, and proposed effects to an immutable SHA-256 approval digest.
+- **Distinct mutation approval:** Submitting a cluster operation requires affirmative approval matching the preview digest and explicit destination authorization (destination, operation, credential/session). Changing targets or effects invalidates approval and fails closed.
+- **Evidence status:** Labeled `unverified` (Google AX prerelease). No live cluster was contacted during local tests.
+- **Installation:** Optional extra: `pip install "specly[ax]"`.
+
+## Development & Testing
+
+```bash
+# Verify asset synchronization against canonical repository sources
+python3 python/scripts/sync_assets.py --check
+
+# Run test suite
+PYTHONPATH=python/src python3 -m unittest discover -s python/tests
+
+# Build isolated wheel
+uv build --wheel --no-sources
+```

specly-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "specly"
+version = "0.1.0"
+description = "Spec-Driven Development scaffolding in Python"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "davidops" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = []
+
+[project.optional-dependencies]
+strands = ["strands-agents>=1.0.0"]
+ax = []
+
+[project.scripts]
+specly = "specly_cli.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+specly_cli = ["assets/*", "assets/templates/*"]

specly-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

specly-0.1.0/src/specly.egg-info/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: specly
+Version: 0.1.0
+Summary: Spec-Driven Development scaffolding in Python
+Author: davidops
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: strands
+Requires-Dist: strands-agents>=1.0.0; extra == "strands"
+Provides-Extra: ax
+
+# Specly Python CLI (Local Preview)
+
+Standalone Python distribution for **Specly** — Spec-Driven Development scaffolding without requiring Node.js.
+
+> **Status:** Local development and testing only. This package is **not published** to PyPI or any public registry. The package name and public command identities remain provisional.
+
+## Supported Commands
+
+- `specly init [options]`: Generate SDD files conforming to canonical artifact contract v1.
+- `specly doctor`: Read-only readiness check for Python runtime (>=3.10), agent markers, and packaged template fingerprints.
+- `specly plan <feature>`: Read-only preview of proposed local file writes and effects.
+- `specly verify <feature>`: Read-only verification of local specification files and checklist progress.
+
+*Note: `specly run` and `specly recover` are not supported in the Python CLI and remain available via the Node CLI.*
+
+## Interruption & Overwrite Safety
+
+- Running `init` on existing files checks their SHA-256 against canonical templates.
+- Files matching canonical template bytes are reported as already complete and skipped.
+- Modified or partial files trigger a warning requiring review; they are never overwritten without explicit `--force`.
+
+## Optional Strands Task Execution Adapter
+
+The optional module `specly_cli.optional.strands_adapter` provides a strictly bounded task-execution boundary using the Strands Agents SDK:
+
+- **Disabled by default:** Default commands (`init`, `doctor`, `plan`, `verify`) never import Strands or inspect ambient credentials.
+- **Explicit authorization:** Execution requires an `ExecutionRequest` bound to an affirmative `approval_digest`, explicit provider configuration, and task ID.
+- **Strict safety boundary:**
+  - Allowed tools are restricted to structured, data-only local operations (`write-file`). Shell, subprocess, VCS, PR, and network tools are prohibited.
+  - Writable roots are confined to the project root; directory traversal, symlink escapes, and reserved paths (`.git`, `.specly`) fail closed.
+  - Resource limits (`budget_calls`, `timeout_seconds`) halt execution with a `limited` status and claim no success.
+- **Evidence distinction:** An `ExecutionRecord` documents tool outcomes and status, but **never** marks tasks checked or implies requirements acceptance. Local unit tests run against local mock fixtures and contact no external providers.
+- **Installation:** Optional extra: `pip install "specly[strands]"`.
+
+## Optional Google AX Cluster Adapter
+
+The optional module `specly_cli.optional.ax_adapter` provides read-only prerequisite diagnostics and effect previews for Google AX / Agent Substrate:
+
+- **Disabled by default:** Default commands never import AX or inspect `KUBECONFIG` / ambient cluster credentials.
+- **Offline diagnostics:** Local inspection checks required binaries (`kubectl`, `ko`, `go`) without probing remote clusters or networks.
+- **Immutable effect preview:** Previews bind context, namespace, operation, resource targets, and proposed effects to an immutable SHA-256 approval digest.
+- **Distinct mutation approval:** Submitting a cluster operation requires affirmative approval matching the preview digest and explicit destination authorization (destination, operation, credential/session). Changing targets or effects invalidates approval and fails closed.
+- **Evidence status:** Labeled `unverified` (Google AX prerelease). No live cluster was contacted during local tests.
+- **Installation:** Optional extra: `pip install "specly[ax]"`.
+
+## Development & Testing
+
+```bash
+# Verify asset synchronization against canonical repository sources
+python3 python/scripts/sync_assets.py --check
+
+# Run test suite
+PYTHONPATH=python/src python3 -m unittest discover -s python/tests
+
+# Build isolated wheel
+uv build --wheel --no-sources
+```

specly-0.1.0/src/specly.egg-info/SOURCES.txt

@@ -0,0 +1,30 @@
+README.md
+pyproject.toml
+src/specly.egg-info/PKG-INFO
+src/specly.egg-info/SOURCES.txt
+src/specly.egg-info/dependency_links.txt
+src/specly.egg-info/entry_points.txt
+src/specly.egg-info/requires.txt
+src/specly.egg-info/top_level.txt
+src/specly_cli/__init__.py
+src/specly_cli/__main__.py
+src/specly_cli/cli.py
+src/specly_cli/contract.py
+src/specly_cli/layout.py
+src/specly_cli/assets/artifact-contract-v1.json
+src/specly_cli/assets/how-to-use.md
+src/specly_cli/assets/templates/design.md
+src/specly_cli/assets/templates/requirements.md
+src/specly_cli/assets/templates/steering.md
+src/specly_cli/assets/templates/tasks.md
+src/specly_cli/assets/templates/verification.md
+src/specly_cli/optional/__init__.py
+src/specly_cli/optional/ax_adapter.py
+src/specly_cli/optional/strands_adapter.py
+tests/test_ax_adapter.py
+tests/test_cli.py
+tests/test_conformance.py
+tests/test_contract.py
+tests/test_strands_adapter.py
+tests/test_sync_assets.py
+tests/test_wheel_smoke.py

specly-0.1.0/src/specly.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

specly-0.1.0/src/specly.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+specly = specly_cli.cli:main

specly-0.1.0/src/specly.egg-info/requires.txt

@@ -0,0 +1,5 @@
+
+[ax]
+
+[strands]
+strands-agents>=1.0.0

specly-0.1.0/src/specly.egg-info/top_level.txt

@@ -0,0 +1 @@
+specly_cli

specly-0.1.0/src/specly_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Specly CLI - Spec-Driven Development scaffolding in Python."""
+
+__version__ = "0.1.0"

specly-0.1.0/src/specly_cli/__main__.py

@@ -0,0 +1,7 @@
+"""Entry point for python -m specly_cli."""
+
+import sys
+from specly_cli.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

specly-0.1.0/src/specly_cli/assets/artifact-contract-v1.json

@@ -0,0 +1,76 @@
+{
+  "contract": "specly-generated-artifacts",
+  "contractVersion": "1.0.0",
+  "schemaVersion": 1,
+  "featurePlaceholder": "{feature}",
+  "artifacts": [
+    {
+      "id": "requirements",
+      "role": "feature specification",
+      "directory": "specsDir",
+      "file": "requirements.md",
+      "template": "src/templates/requirements.md",
+      "sha256": "e94b31549542afa380a0814e4b53e67f77393f6949fbc7addbdacec99f213365",
+      "ownership": "user"
+    },
+    {
+      "id": "design",
+      "role": "technical design",
+      "directory": "specsDir",
+      "file": "design.md",
+      "template": "src/templates/design.md",
+      "sha256": "e27dc44a125652c728674637be6da821355f48027cad76a1d5d88bbe9869bd87",
+      "ownership": "user"
+    },
+    {
+      "id": "tasks",
+      "role": "implementation tasks",
+      "directory": "specsDir",
+      "file": "tasks.md",
+      "template": "src/templates/tasks.md",
+      "sha256": "4566c01228d85a4c93f0b3a3e71ee36b46ae8e408434f0a38ac55cf644db3c4d",
+      "ownership": "user"
+    },
+    {
+      "id": "verification",
+      "role": "verification checklist",
+      "directory": "specsDir",
+      "file": "verification.md",
+      "template": "src/templates/verification.md",
+      "sha256": "eb17232f8316d97fae36432600adbbfedc1b2808bb68a052951b69f5164a23ef",
+      "ownership": "user"
+    },
+    {
+      "id": "steering",
+      "role": "persistent project context",
+      "directory": "steeringDir",
+      "file": "steering.md",
+      "template": "src/templates/steering.md",
+      "sha256": "4607049ab708123603c0fc627eab4bf7d4eaf3eea2e524f1b8c68178cf6ac2b1",
+      "ownership": "user"
+    },
+    {
+      "id": "guide",
+      "role": "usage documentation",
+      "directory": "agentDir",
+      "file": "how-to-use.md",
+      "template": "how-to-use.md",
+      "sha256": "0d09f70b6f6965509589b6a424c7d3f14a42cf3df134b1b4ed2061d5a77956e5",
+      "ownership": "user"
+    }
+  ],
+  "layouts": {
+    "generic": { "specsDir": "specs", "steeringDir": "specs", "agentDir": "specs" },
+    "cursor": { "specsDir": ".cursor/specs/{feature}", "steeringDir": ".cursor", "agentDir": ".cursor" },
+    "kiro": { "specsDir": ".kiro/specs/{feature}", "steeringDir": ".kiro", "agentDir": ".kiro" },
+    "vscode": { "specsDir": ".vscode/specs/{feature}", "steeringDir": ".vscode", "agentDir": ".vscode" },
+    "antigravity": { "specsDir": ".agent/specs/{feature}", "steeringDir": ".agent", "agentDir": ".agent" },
+    "windsurf": { "specsDir": ".windsurf/specs/{feature}", "steeringDir": ".windsurf", "agentDir": ".windsurf" },
+    "claude": { "specsDir": ".claude/specs/{feature}", "steeringDir": ".claude", "agentDir": ".claude" }
+  },
+  "overwritePolicy": {
+    "default": "skip-existing",
+    "explicitForce": "replace-existing",
+    "migration": "never-overwrite-user-owned-artifacts-without-explicit-force"
+  }
+}

specly-0.1.0/src/specly_cli/assets/how-to-use.md

@@ -0,0 +1,226 @@
+# How to Use SDD (Spec-Driven Development)
+
+**Author:** [davidops](https://www.npmjs.com/~davidops)
+
+This package scaffolds the minimum structure for **Spec-Driven Development**: specifications that guide the AI agent before writing code.
+
+## Quick Start
+
+From any project root:
+
+```bash
+npx specly
+```
+
+This creates the 5 base spec files adapted to the agent detected in your project, plus a copy of this guide inside your IDE workspace.
+
+## The 5 Generated Files
+
+| File               | Role              | Contents                                                |
+|--------------------|-------------------|---------------------------------------------------------|
+| `requirements.md`  | The **what**      | User stories + testable EARS criteria + ambiguity hunt  |
+| `design.md`        | The **how**       | 7 fixed sections (architecture, components, data, error handling, security, testing) + Mermaid diagrams |
+| `tasks.md`         | The **order**     | Checklist with max 2 hierarchy levels + slicing rules + atomic commit guidance |
+| `verification.md`  | The **done**      | Post-implementation validation checklist against requirements, design, and code quality |
+| `steering.md`      | **Context**       | Stack, rules, hooks, MCP servers, skills, and project conventions |
+
+## Workflow
+
+```
+Idea → Requirements → Design → Tasks → Build → Validate
+```
+
+1. Write `requirements.md` with user stories and EARS criteria. Hunt for ambiguities before moving on.
+2. Design the solution in `design.md` (7 sections — architecture, components, data, error handling, security, testing).
+3. Break work into tasks in `tasks.md` (checkboxes). Slice until each task is small and focused.
+4. Keep `steering.md` updated with project context, hooks, MCP servers, and conventions.
+5. Ask the agent to execute tasks one by one, validating against EARS criteria.
+6. Run `verification.md` after implementation — check every box before closing the feature.
+
+**Golden rule:** when something changes, fix the spec first — do not patch code. Validate before merging.
+
+## Hooks (Automations)
+
+Hooks are scripts that run automatically on events (pre-commit, pre-push, etc.).
+They catch errors before they reach the repo.
+
+### Example: pre-commit hook that runs tests
+
+For Kiro (`.kiro/hooks/`):
+
+```bash
+#!/bin/sh
+npm test
+```
+
+For generic projects (`.githooks/`), enable with:
+
+```bash
+git config core.hooksPath .githooks
+```
+
+### Recommended hook pipeline
+
+1. **Pre-commit**: lint + format + secret scanner
+2. **Pre-push**: full test suite
+3. **Post-merge**: update dependencies or deploy
+
+## MCP / NCP Servers (External Context)
+
+MCP servers connect the agent to live documentation, APIs, or databases.
+They reduce hallucinations by providing current data instead of relying on training cutoffs.
+
+### Examples
+
+| Server             | Purpose                        | When to use                              |
+|--------------------|--------------------------------|------------------------------------------|
+| `aws-documentation` | Search and read AWS docs       | Building on AWS                          |
+| `aws-pricing`       | Live pricing lookups           | Cost estimation                          |
+| `aws-iac`           | CloudFormation validation + CDK | Infrastructure as Code                   |
+| `context7`          | Library docs (React, Next.js, Prisma, etc.) | Using third-party libraries    |
+| `websearch`         | General web search             | Latest information not in training data   |
+
+Configure MCP servers in your agent's settings (e.g., `opencode.json` for OpenCode, `.cursor/mcp.json` for Cursor).
+
+## Skills (On-Demand Instructions)
+
+Skills are markdown files activated by keywords. They teach the agent how to do specific tasks without repeating instructions.
+
+### Quick setup
+
+Create `.kiro/skills/review-pr.md` (for Kiro) or `skills/review-pr.md` (generic) with:
+
+```markdown
+# Skill: Review PR
+
+Activate when the user says "review this PR" or uses `/review-pr`.
+
+## Steps
+1. Read the diff against the base branch
+2. Check every file for:
+   - Secrets or credentials in code
+   - Debug artifacts (console.log, TODO, commented code)
+   - Missing error handling
+3. Verify EARS criteria from requirements.md are met
+4. Report findings as a checklist
+```
+
+The agent loads the skill automatically when the keyword is mentioned.
+
+## Supported Agents
+
+The CLI auto-detects the agent from existing project folders:
+
+| Agent       | Flag                  | Specs path                     | Steering              | Hooks path       |
+|-------------|-----------------------|--------------------------------|-----------------------|------------------|
+| Generic     | `--agent generic`     | `specs/`                       | `specs/steering.md`   | `.githooks/`     |
+| Cursor      | `--agent cursor`      | `.cursor/specs/<feature>/`    | `.cursor/steering.md` | —                |
+| Kiro        | `--agent kiro`        | `.kiro/specs/<feature>/`      | `.kiro/steering.md`   | `.kiro/hooks/`   |
+| VS Code     | `--agent vscode`      | `.vscode/specs/<feature>/`    | `.vscode/steering.md`  | —                |
+| Antigravity | `--agent antigravity` | `.agent/specs/<feature>/`     | `.agent/steering.md`   | —                |
+| Windsurf    | `--agent windsurf`    | `.windsurf/specs/<feature>/`  | `.windsurf/steering.md` | —                |
+| Claude Code | `--agent claude`      | `.claude/specs/<feature>/`    | `.claude/steering.md`  | —                |
+
+### Examples
+
+```bash
+# Auto-detect
+npx specly
+
+# Cursor with feature "auth"
+npx specly --agent cursor --feature auth
+
+# Kiro with feature "payments"
+npx specly --agent kiro -n payments
+
+# Generic structure (works in any editor)
+npx specly --agent generic
+
+# List all agents
+npx specly --list
+```
+
+## CLI Options
+
+```
+npx specly [options]
+
+  -a, --agent <name>      Force target agent
+  -n, --feature <name>    Feature name (default: starter)
+  -f, --force             Overwrite existing files
+  -l, --list              List supported agents
+  -h, --help              Show help
+```
+
+## EARS Criteria (Templates)
+
+Use these keywords in `requirements.md` for testable criteria:
+
+| Keyword       | Use case                         | Example                                                          |
+|---------------|----------------------------------|------------------------------------------------------------------|
+| `WHEN`        | Trigger event                    | WHEN the user saves THE SYSTEM SHALL persist the data            |
+| `IF...THEN`   | Undesired condition / error      | IF the title is empty THEN THE SYSTEM SHALL show an error        |
+| `WHILE`       | Continuous state                 | WHILE filters are active THE SYSTEM SHALL filter results         |
+| `WHERE`       | Location context                 | WHERE the user is admin THE SYSTEM SHALL show the panel          |
+| `AS SOON AS`  | Time-sensitive response          | AS SOON AS the payment completes THE SYSTEM SHALL send a receipt |
+
+### Ambiguity Hunting
+
+Before accepting requirements, ask:
+
+- What happens when the input is empty? Malformed? Too large?
+- Who exactly is "the user"? Anonymous? Authenticated? Admin?
+- What does "fast" mean in milliseconds? What does "a few" mean in numbers?
+- What happens if an external service is down?
+
+## Prompting Your Agent
+
+Once files are generated, use prompts like:
+
+```
+Read specs/requirements.md and specs/design.md.
+Execute task 1.1 from tasks.md.
+Validate the result against the EARS criteria.
+```
+
+For agents with per-feature folders:
+
+```
+Read .cursor/specs/auth/requirements.md and execute task 2.1 from tasks.md.
+```
+
+For validation after implementation:
+
+```
+Read specs/verification.md and run each check against the implementation.
+```
+
+## Task Slicing Guidelines
+
+- If a task has more than 5 sub-steps, split it.
+- One task = one logical change.
+- Each task should feel like "I know exactly what to do here."
+- One commit per checked task when possible.
+- Mark a task complete only after it is tested and reviewed.
+
+## Security
+
+- AI-generated code is a **draft**, not a deliverable.
+- Verify: does it compile? do tests pass? does it meet EARS criteria?
+- Never commit secrets. Use environment variables or Secrets Manager.
+- Review diffs before accepting agent changes.
+- Enable secret scanning in CI (e.g., GitGuardian, truffleHog).
+- Use `.gitignore` (and `.kiroignore` for Kiro) to exclude sensitive files.
+
+## Global Install (Optional)
+
+```bash
+npm install -g specly
+specly --agent cursor --feature my-feature
+```
+
+On install, this guide is copied into your project and opened in your IDE.
+
+---
+
+**First time?** Open `requirements.md` and replace the placeholders with your real feature. Then run through the workflow: Requirements → Design → Tasks → Build → Validate.

specly-0.1.0/src/specly_cli/assets/templates/design.md

@@ -0,0 +1,51 @@
+# Design
+
+> Describe **how** to implement technically. Keep the 6 fixed sections.
+
+## 1. Overview
+
+[Brief summary of the feature, goal, and scope.]
+
+## 2. Architecture
+
+[High-level decisions: patterns, layers, integrations.]
+
+- [Component or layer 1]
+- [Component or layer 2]
+
+## 3. Components
+
+| Component | Responsibility |
+|-----------|----------------|
+| [Name]    | [What it does] |
+
+## 4. Data Models
+
+[Entities, relationships, and data flows. Use Mermaid when helpful.]
+
+```mermaid
+flowchart LR
+  A[Input] --> B[Process]
+  B --> C[Output]
+```
+
+## 5. Error Handling
+
+- [Error scenario 1] → [Expected response]
+- [Error scenario 2] → [Expected response]
+- [Error scenario 3 (external dependency failure)] → [Fallback / retry strategy]
+
+## 6. Security
+
+- **Authentication**: [How the user/system identity is verified]
+- **Authorization**: [Permission model — who can do what]
+- **Secrets**: [Where credentials live — env vars, secrets manager; never in code]
+- **Data protection**: [Encryption at rest and in transit, PII handling]
+- **Audit**: [Logging sensitive operations]
+
+## 7. Testing
+
+- [ ] Unit test: [EARS criterion it validates]
+- [ ] Integration test: [end-to-end flow]
+- [ ] Regression test: [edge case]
+- [ ] Security test: [auth, injection, or permission scenario]