specly 0.1.0__py3-none-any.whl

specly-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,20 @@
+specly_cli/__init__.py,sha256=QDh0bhdjzfE8nh1sJhU2y8pFIy4F1wUAleWES3gSqhM,89
+specly_cli/__main__.py,sha256=SkqPuBD1h6n4E0LFOspmdeiZ3b7H4QpikG4pK8tEeiE,137
+specly_cli/cli.py,sha256=Gm7rS4ct5CDwjd7LSulWKtqdPmX_pBUEqE6BQkCs8D0,10225
+specly_cli/contract.py,sha256=JYbrQtp073xIvrO7oQclvdCsDkcFc_6bt5OGtTjZlfY,3705
+specly_cli/layout.py,sha256=GW3Rkzl5ZUdQ1nzKOfps7WeNF8d03NTXvtkcEw6Qi0Y,4348
+specly_cli/assets/artifact-contract-v1.json,sha256=iTV5HK7mmS2BXJtjNYlPXxcdVxUW4lULC9yMSrjtgr0,2834
+specly_cli/assets/how-to-use.md,sha256=DQn3C29pZVCVibakJMfT8UpCzz3xNLG07SBh1ad5VuU,8824
+specly_cli/assets/templates/design.md,sha256=4n3EShJWUscoZ0Y3vm2oITVfSAJ8rXah1diLvphpvYc,1293
+specly_cli/assets/templates/requirements.md,sha256=6UsxVJVCr6OAoIFOS1Pmf3c5P2lJ-8et29rOyZ8hM2U,2243
+specly_cli/assets/templates/steering.md,sha256=RgcEmrcIEjYDwPxifqtL99Tq8-6i5STxuMaBeM9qwrE,3119
+specly_cli/assets/templates/tasks.md,sha256=RWbAEijYWkyT8LOj5x7ja0aujkCENPCjisVc9kTbPE0,1425
+specly_cli/assets/templates/verification.md,sha256=6xcjL4MW2X-uNkMmAK27_twbKAi7aKBSlRtp9RZKI-8,1381
+specly_cli/optional/__init__.py,sha256=V4WeN0_dB1fsVlhtnEUWYBViaoQH8XSoNmh7_3Mhg3k,40
+specly_cli/optional/ax_adapter.py,sha256=INHqwmWX0FChFrItUQ73d5pisCX5hZWdbBT9MU7zKBE,5263
+specly_cli/optional/strands_adapter.py,sha256=mtU14-aFMXnKuvT1eicJNVg6nbQpyRsm32FGWMBJbtE,5432
+specly-0.1.0.dist-info/METADATA,sha256=EEzxV8R9qO9YNXXWbEeqso0sQTjE4hL79nl3MVV7a58,4242
+specly-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+specly-0.1.0.dist-info/entry_points.txt,sha256=Qa6YdwE5G-LLc3mQM0dxFPagB7wj86s64oblGWHXoew,47
+specly-0.1.0.dist-info/top_level.txt,sha256=LACTfPYY1IIHWsvemDKpfu8FWGzj78qcs2isweSmRrg,11
+specly-0.1.0.dist-info/RECORD,,

specly-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

specly-0.1.0.dist-info/entry_points.txt

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

specly-0.1.0.dist-info/top_level.txt

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

specly_cli/__init__.py

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

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_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_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_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]

specly_cli/assets/templates/requirements.md

@@ -0,0 +1,49 @@
+# Requirements
+
+> Define **what** to build and **why**. Use user stories and testable EARS criteria.
+> Before writing code, hunt for ambiguities: vague terms, missing edge cases, undefined actors.
+
+## Feature: [Feature Name]
+
+### User Story 1
+As a [role], I want [action] so that [benefit].
+
+#### Acceptance Criteria (EARS)
+- WHEN [trigger event] THE SYSTEM SHALL [expected behavior]
+- IF [undesired condition] THEN THE SYSTEM SHALL [error handling or alternative]
+- WHILE [continuous state] THE SYSTEM SHALL [keep reacting]
+- WHERE [specific context or location] THE SYSTEM SHALL [contextual behavior]
+- AS SOON AS [event] THE SYSTEM SHALL [time-sensitive response]
+
+### User Story 2
+As a [role], I want [action] so that [benefit].
+
+#### Acceptance Criteria
+- WHEN [event] THE SYSTEM SHALL [behavior]
+- IF [error case] THEN THE SYSTEM SHALL [fallback]
+
+---
+
+## Ambiguity Checklist
+
+Before approving requirements, verify:
+
+- [ ] Every noun is clearly defined (no "user" when you mean "admin")
+- [ ] Every condition has a negative case (what happens when it fails?)
+- [ ] Numbers have explicit limits ("at most 5", not "a few")
+- [ ] Temporal words are precise ("within 2 seconds", not "instantly")
+- [ ] Actors are identified (who triggers? who receives?)
+
+---
+
+## EARS Reference
+
+| Keyword       | Use case                         | Example                                                          |
+|---------------|----------------------------------|------------------------------------------------------------------|
+| `WHEN`        | Trigger event (ubiquitous)       | WHEN the user submits THE SYSTEM SHALL validate the form         |
+| `IF...THEN`   | Undesired condition / error      | IF the email is invalid THEN THE SYSTEM SHALL show an error      |
+| `WHILE`       | Continuous state                 | WHILE the upload is in progress THE SYSTEM SHALL show a spinner  |
+| `WHERE`       | Location or feature 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 |
+
+**Rule:** If you cannot test it, it is not clear enough yet. If a criterion does not have a clear pass/fail, rewrite it.

specly_cli/assets/templates/steering.md

@@ -0,0 +1,91 @@
+# Steering
+
+> Persistent project context. The agent should read this file every session.
+
+## Purpose
+
+[Why this project exists and what problem it solves.]
+
+## Principles
+
+- Prioritize clarity over speed.
+- Avoid ambiguity in requirements and tasks.
+- Treat generated code as a draft until review and tests pass.
+- When something changes, fix the spec before patching code.
+- Validate before merging: tests + EARS criteria + security review.
+
+## Stack
+
+- [Primary language / framework]
+- [Database / services]
+- [Build and test tools]
+- [Cloud provider / deployment target]
+
+## Project Structure
+
+```
+[Relevant folder tree]
+```
+
+## Agent Rules
+
+- Read `requirements.md`, `design.md`, `tasks.md`, and `steering.md` before proposing changes.
+- If context is missing, ask before inventing.
+- Write acceptance criteria in testable format (EARS).
+- Split work into small, verifiable tasks.
+- Keep traceability between requirements, design, and tasks.
+- Run the verification checklist after implementation.
+
+## Conventions
+
+- `requirements.md` → the **what**
+- `design.md` → the **how**
+- `tasks.md` → the **order**
+- `verification.md` → the **done checklist**
+- `steering.md` → **context** and rules
+
+## Hooks (Automations)
+
+> Hooks are scripts that run automatically on events (pre-commit, pre-push, post-merge).
+
+- [ ] Pre-commit: lint + format + secret scanner
+- [ ] Pre-push: run full test suite
+- [ ] Post-merge: update changelog or deploy
+
+Store hook scripts in:
+- Kiro: `.kiro/hooks/`
+- Generic: `.githooks/`
+
+## 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.
+
+| Server      | Purpose                  | Source                      |
+|-------------|--------------------------|-----------------------------|
+| [name]      | [what it provides]       | [URL or package]            |
+
+Example MCP servers from the AWS ecosystem:
+- `aws-documentation` — search and read AWS docs
+- `aws-pricing` — live pricing lookups
+- `aws-iac` — CloudFormation validation + CDK patterns
+
+## Skills (On-Demand Instructions)
+
+> Skills are markdown files activated by keywords. They teach the agent how to do specific tasks.
+
+| Keyword                     | Skill file                  | What it does                  |
+|-----------------------------|-----------------------------|-------------------------------|
+| `review-pr`                 | `skills/review-pr.md`       | PR template + review steps    |
+| [your-keyword]              | `skills/[name].md`          | [description]                 |
+
+Store skills in `.kiro/skills/` (Kiro) or `skills/` (generic).
+
+## Security
+
+- Do not commit secrets to the repository.
+- Store credentials in environment variables or secrets manager, never in code.
+- Always review the diff before accepting changes.
+- Use `.gitignore` (and `.kiroignore` for Kiro) to exclude sensitive files.
+- Follow the principle of least privilege for all tokens and roles.
+- Enable secret scanning in CI (e.g., GitGuardian, truffleHog).

specly_cli/assets/templates/tasks.md

@@ -0,0 +1,40 @@
+# Tasks
+
+> Define the **order** of implementation. Max 2 hierarchy levels. Each task references its Requirements.
+
+- [ ] 1. [Main task — references User Story 1]
+  - [ ] 1.1 [Verifiable sub-task — small enough to review in one pass]
+  - [ ] 1.2 [Verifiable sub-task]
+
+- [ ] 2. [Main task — references User Story 2]
+  - [ ] 2.1 [Verifiable sub-task]
+  - [ ] 2.2 [Verifiable sub-task]
+
+- [ ] 3. Validation and wrap-up
+  - [ ] 3.1 Verify EARS criteria from requirements.md
+  - [ ] 3.2 Run tests defined in design.md
+  - [ ] 3.3 Security review: no secrets leaked, proper auth checks
+  - [ ] 3.4 Update steering.md if new conventions emerged
+
+---
+
+## Rules
+
+### Task Slicing
+- If a task has more than 5 sub-steps, split it into smaller tasks.
+- One task = one logical change. If it does two unrelated things, split it.
+- Each task should feel like "I know exactly what to do here."
+
+### Atomic Commits
+- One commit per checked task (when possible).
+  ```
+  feat(auth): implement login validation
+  ```
+- If a task spans multiple files but is one logical change, it is still one commit.
+- Mark `[x]` only when the task is verified (tested + reviewed).
+- Never commit secrets, API keys, or credentials.
+
+### Traceability
+- Every task references a requirement or design section.
+- If a task does not trace back to a requirement, does it belong here?
+- After all tasks are done, run verification.md against the implementation.