maurao-method 0.0.0-stage → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/.clinerules/maurao-method.md +6 -0
  2. package/.cursor/rules/maurao-method.mdc +7 -0
  3. package/.github/copilot-instructions.md +6 -0
  4. package/.github/workflows/ci.yml +39 -0
  5. package/.github/workflows/publish.yml +32 -0
  6. package/.github/workflows/release-on-main.yml +87 -0
  7. package/.maurao/README.md +13 -0
  8. package/.maurao/config.json +17 -0
  9. package/AGENTS.md +30 -0
  10. package/CLAUDE.md +6 -0
  11. package/GEMINI.md +6 -0
  12. package/README.md +110 -2
  13. package/bin/maurao.mjs +218 -0
  14. package/commands/debug.md +4 -0
  15. package/commands/discover.md +4 -0
  16. package/commands/map.md +4 -0
  17. package/commands/plan.md +4 -0
  18. package/commands/pr.md +4 -0
  19. package/commands/review.md +4 -0
  20. package/commands/specify.md +4 -0
  21. package/commands/spike.md +4 -0
  22. package/commands/verify.md +4 -0
  23. package/docs/artifact-contract.md +22 -0
  24. package/docs/commands.md +32 -0
  25. package/docs/method-overview.md +32 -0
  26. package/docs/npm-release.md +68 -0
  27. package/docs/portable-adapters.md +26 -0
  28. package/docs/project-modes.md +33 -0
  29. package/docs/specification-standard.md +25 -0
  30. package/docs/tool-support.md +24 -0
  31. package/docs/workflow.md +45 -0
  32. package/package.json +42 -4
  33. package/skills/core/architecture/SKILL.md +16 -0
  34. package/skills/core/brownfield-analysis/SKILL.md +20 -0
  35. package/skills/core/debugging/SKILL.md +32 -0
  36. package/skills/core/planning/SKILL.md +18 -0
  37. package/skills/core/product-discovery/SKILL.md +20 -0
  38. package/skills/core/project-discovery/SKILL.md +32 -0
  39. package/skills/core/requirements/SKILL.md +13 -0
  40. package/skills/core/specification/SKILL.md +41 -0
  41. package/skills/core/spike/SKILL.md +30 -0
  42. package/skills/core/technology-discovery/SKILL.md +43 -0
  43. package/skills/practices/code-review/SKILL.md +21 -0
  44. package/skills/practices/data-migration/SKILL.md +14 -0
  45. package/skills/practices/observability/SKILL.md +28 -0
  46. package/skills/practices/observability/checklist.md +11 -0
  47. package/skills/practices/observability/references/dotnet.md +7 -0
  48. package/skills/practices/observability/references/java.md +9 -0
  49. package/skills/practices/observability/references/node.md +7 -0
  50. package/skills/practices/observability/references/python.md +7 -0
  51. package/skills/practices/observability/templates/logging-plan.md +16 -0
  52. package/skills/practices/observability/templates/metrics-plan.md +6 -0
  53. package/skills/practices/observability/templates/tracing-plan.md +14 -0
  54. package/skills/practices/pull-request/SKILL.md +17 -0
  55. package/skills/practices/release-readiness/SKILL.md +20 -0
  56. package/skills/practices/security/SKILL.md +11 -0
  57. package/skills/practices/testing/SKILL.md +37 -0
  58. package/skills/practices/verification/SKILL.md +15 -0
  59. package/skills/workflows/brownfield-change/SKILL.md +26 -0
  60. package/skills/workflows/bug-fix/SKILL.md +19 -0
  61. package/skills/workflows/feature-development/SKILL.md +35 -0
  62. package/skills/workflows/greenfield-product/SKILL.md +28 -0
  63. package/technology-packs/dotnet/README.md +6 -0
  64. package/technology-packs/java/README.md +34 -0
  65. package/technology-packs/node/README.md +6 -0
  66. package/technology-packs/python/README.md +6 -0
  67. package/templates/brownfield-map.md +38 -0
  68. package/templates/bug-fix.md +36 -0
  69. package/templates/change-proposal.md +40 -0
  70. package/templates/decision-record.md +33 -0
  71. package/templates/feature-spec.md +50 -0
  72. package/templates/implementation-plan.md +33 -0
  73. package/templates/product-brief.md +41 -0
  74. package/templates/pull-request.md +27 -0
  75. package/templates/spike-report.md +36 -0
  76. package/templates/system-context.md +36 -0
  77. package/templates/technology-inventory.md +38 -0
  78. package/templates/test-plan.md +23 -0
  79. package/templates/threat-model.md +31 -0
  80. package/templates/verification-report.md +26 -0
@@ -0,0 +1,14 @@
1
+ ---
2
+ name: data-migration
3
+ description: Plan and verify safe schema or data changes with compatibility, rollout, and rollback considerations.
4
+ ---
5
+
6
+ # Data Migration
7
+
8
+ 1. Inventory current schema and data invariants.
9
+ 2. Define the target state and compatibility window.
10
+ 3. Prefer expand-and-contract for live systems.
11
+ 4. Make migration steps observable and restartable where possible.
12
+ 5. Define backfill limits, validation, failure handling, and rollback or forward-fix strategy.
13
+ 6. Test with representative data without exposing production secrets.
14
+
@@ -0,0 +1,28 @@
1
+ ---
2
+ name: observability
3
+ description: Define operational signals that make software behavior diagnosable in development and production.
4
+ ---
5
+
6
+ # Observability
7
+
8
+ Consider observability whenever a change affects a request path, background job, integration, persistence, security boundary, or user-visible failure.
9
+
10
+ Start by writing the operational question: what must an engineer know when this behavior is slow, failing, incorrect, or expensive?
11
+
12
+ ## Signals
13
+
14
+ - Logs: meaningful events with stable fields and safe redaction.
15
+ - Metrics: counters, gauges, and latency distributions tied to operational questions.
16
+ - Traces: causal flow across service and integration boundaries.
17
+ - Errors: actionable classification, context, and correlation identifiers.
18
+
19
+ ## Rules
20
+
21
+ - Do not log secrets, tokens, credentials, or unnecessary personal data.
22
+ - Prefer structured data over strings that cannot be queried.
23
+ - Define the diagnostic question each signal answers.
24
+ - Keep local development and production behavior compatible where practical.
25
+ - Define useful behavior for success, failure, retry, timeout, and degraded operation.
26
+ - Avoid high-cardinality dimensions and uncontrolled payload logging.
27
+ - Prefer correlation that follows a request, job, message, or business operation across boundaries.
28
+
@@ -0,0 +1,11 @@
1
+ # Observability checklist
2
+
3
+ - [ ] What operational question must be answered?
4
+ - [ ] Is the relevant event logged with structured fields?
5
+ - [ ] Are secrets and personal data excluded or redacted?
6
+ - [ ] Is success measurable with a counter or result metric?
7
+ - [ ] Is latency or duration measurable where relevant?
8
+ - [ ] Is failure classified consistently?
9
+ - [ ] Can a request or job be correlated across boundaries?
10
+ - [ ] Is the signal useful in the target environment?
11
+
@@ -0,0 +1,7 @@
1
+ # .NET observability reference
2
+
3
+ - Prefer the existing `ILogger` and `Activity`/OpenTelemetry conventions in the project.
4
+ - Use structured message properties rather than interpolated diagnostic strings.
5
+ - Preserve trace context across HTTP clients, messaging, and background services.
6
+ - Redact credentials, tokens, connection strings, and personal data.
7
+
@@ -0,0 +1,9 @@
1
+ # Java observability reference
2
+
3
+ - Prefer the project's existing logging facade and telemetry conventions.
4
+ - Use structured fields and stable event names rather than concatenated messages.
5
+ - Preserve context across servlet or reactive requests, executors, schedulers, messaging, and database calls.
6
+ - Redact authorization headers, cookies, credentials, tokens, connection strings, and personal data.
7
+ - Treat blocking calls, retries, timeouts, and thread-pool saturation as operational signals where relevant.
8
+ - If OpenTelemetry is present, preserve trace and span context across service boundaries without creating uncontrolled cardinality.
9
+
@@ -0,0 +1,7 @@
1
+ # Node.js observability reference
2
+
3
+ - Prefer the project's existing logger and telemetry libraries.
4
+ - Use structured JSON in production and readable output locally when supported.
5
+ - Preserve async context across HTTP, jobs, and external calls.
6
+ - Redact authorization headers, cookies, tokens, and sensitive payload fields.
7
+
@@ -0,0 +1,7 @@
1
+ # Python observability reference
2
+
3
+ - Prefer the project's existing logging and telemetry stack.
4
+ - Use structured fields and stable event names.
5
+ - Preserve context across async tasks, workers, HTTP clients, and queues.
6
+ - Redact credentials, tokens, personal data, and full request bodies unless explicitly required.
7
+
@@ -0,0 +1,16 @@
1
+ # Logging plan
2
+
3
+ ## Diagnostic question
4
+
5
+ What question should an operator answer from logs?
6
+
7
+ ## Events
8
+
9
+ | Event | Level | Required fields | Redaction |
10
+ |---|---|---|---|
11
+ | | | | |
12
+
13
+ ## Failure behavior
14
+
15
+ -
16
+
@@ -0,0 +1,6 @@
1
+ # Metrics plan
2
+
3
+ | Metric | Type | Dimensions | Question answered |
4
+ |---|---|---|---|
5
+ | | Counter / Gauge / Histogram | | |
6
+
@@ -0,0 +1,14 @@
1
+ # Tracing plan
2
+
3
+ ## Boundaries
4
+
5
+ List service, job, database, queue, and external integration boundaries.
6
+
7
+ ## Span attributes
8
+
9
+ Only include low-cardinality, non-sensitive attributes that help explain latency or failure.
10
+
11
+ ## Correlation
12
+
13
+ Describe how trace, log, and request identifiers relate.
14
+
@@ -0,0 +1,17 @@
1
+ ---
2
+ name: pull-request
3
+ description: Prepare a reviewable pull request with scope, evidence, risks, and reviewer guidance.
4
+ ---
5
+
6
+ # Pull Request
7
+
8
+ - Keep the change focused and split unrelated work.
9
+ - Link the specification, issue, or decision record.
10
+ - Summarize behavior instead of narrating every edit.
11
+ - List exact validation commands and results.
12
+ - State known limitations, rollout risk, and rollback strategy.
13
+ - Call out migrations, configuration, security, or observability changes.
14
+ - Do not describe unexecuted checks as passing.
15
+
16
+ Use `templates/pull-request.md` as the default structure.
17
+
@@ -0,0 +1,20 @@
1
+ ---
2
+ name: release-readiness
3
+ description: Determine whether a change can be delivered safely with rollout, rollback, migration, and operational evidence.
4
+ ---
5
+
6
+ # Release Readiness
7
+
8
+ Check:
9
+
10
+ - acceptance criteria and verification status;
11
+ - build, tests, lint, and security checks;
12
+ - configuration and secret requirements;
13
+ - data or schema migration safety;
14
+ - backward compatibility;
15
+ - observability and alerting;
16
+ - rollout controls and rollback path;
17
+ - documentation and support readiness.
18
+
19
+ Create `.maurao/reports/<change-id>-release-readiness.md` and return `Ready`, `Ready with explicit risk`, or `Not ready`, with evidence for the decision.
20
+
@@ -0,0 +1,11 @@
1
+ ---
2
+ name: security
3
+ description: Identify and reduce security, privacy, abuse, and supply-chain risks in a software change.
4
+ ---
5
+
6
+ # Security
7
+
8
+ Consider trust boundaries, authentication, authorization, input handling, secrets, sensitive data, dependency risk, logging exposure, abuse cases, and failure behavior.
9
+
10
+ For high-risk changes, produce `.maurao/reports/<change-id>-threat-model.md` from `templates/threat-model.md`, with assets, actors, entry points, threats, mitigations, verification, and residual risk. Do not treat passing tests as proof that security risk is absent.
11
+
@@ -0,0 +1,37 @@
1
+ ---
2
+ name: testing
3
+ description: Design and execute tests that verify behavior and protect against regressions.
4
+ ---
5
+
6
+ # Testing
7
+
8
+ Derive tests from requirements and acceptance criteria, not from the implementation after it is written.
9
+
10
+ ## Test selection
11
+
12
+ - Unit: pure rules, transformations, and local decisions.
13
+ - Integration: persistence, queues, frameworks, filesystem, and external boundaries under controlled conditions.
14
+ - Contract: public APIs, events, schemas, and compatibility promises.
15
+ - End-to-end: critical user journeys through real application boundaries.
16
+ - Exploratory: unknown behavior, usability, and failure discovery; record the observation.
17
+
18
+ Prefer the narrowest test that proves the behavior, then add broader tests when integration risk requires them.
19
+
20
+ ## Required coverage
21
+
22
+ - happy path;
23
+ - invalid input and authorization failures;
24
+ - boundaries, empty states, timeouts, retries, and partial failure;
25
+ - compatibility behavior for brownfield changes;
26
+ - regression protection for bug fixes;
27
+ - deterministic setup and cleanup.
28
+
29
+ Preserve the project's test style and framework unless there is a concrete reason to change it. Never claim a test passed unless it was executed.
30
+
31
+ ## Completion checklist
32
+
33
+ - Tests cover the changed behavior.
34
+ - Regression coverage exists for fixed bugs.
35
+ - Relevant existing tests were executed.
36
+ - Failures are reported with their actual output and scope.
37
+
@@ -0,0 +1,15 @@
1
+ ---
2
+ name: verification
3
+ description: Verify that an implementation satisfies its specification and report evidence honestly.
4
+ ---
5
+
6
+ # Verification
7
+
8
+ Build a criterion-to-evidence matrix. Use the cheapest reliable check first, then broaden validation according to risk and project depth.
9
+
10
+ Evidence may include executed tests, lint, build output, static analysis, manual inspection, runtime checks, or independent review.
11
+
12
+ Verify both changed behavior and preserved behavior for brownfield work. For greenfield work, verify the smallest useful slice through real boundaries.
13
+
14
+ Classify every result as `Verified`, `Failed`, `Not run`, `Blocked`, or `Assumed`. Never convert an assumption into a verification claim.
15
+
@@ -0,0 +1,26 @@
1
+ ---
2
+ name: brownfield-change
3
+ description: Safely change an existing product by mapping current behavior, preserving invariants, and delivering a reversible increment.
4
+ ---
5
+
6
+ # Brownfield Change
7
+
8
+ Compose `project-discovery`, `technology-discovery`, `brownfield-analysis`, `specification`, `architecture`, `planning`, `testing`, `observability`, `data-migration` when relevant, `code-review`, `verification`, and `release-readiness`.
9
+
10
+ ## Sequence
11
+
12
+ 1. Map the current system and confirm the project baseline.
13
+ 2. Identify behavior, contracts, data, and operational invariants.
14
+ 3. Define the delta and compatibility requirements.
15
+ 4. Choose the smallest change seam and migration strategy.
16
+ 5. Implement in reversible increments.
17
+ 6. Verify new behavior and preserved behavior.
18
+ 7. Prepare rollout, rollback, and operational evidence.
19
+
20
+ ## Outputs and gates
21
+
22
+ - Baseline: `.maurao/system-context.md` and `.maurao/technology-inventory.md`.
23
+ - Change: `.maurao/specifications/<change-id>.md` and `.maurao/plans/<change-id>.md`.
24
+ - Compatibility: invariants and migration strategy reviewed.
25
+ - Delivery: verification and release-readiness reports complete.
26
+
@@ -0,0 +1,19 @@
1
+ ---
2
+ name: bug-fix
3
+ description: Diagnose and fix a defect with a reproducible case, root-cause explanation, and regression protection.
4
+ ---
5
+
6
+ # Bug Fix
7
+
8
+ Compose `debugging`, `testing`, `observability` when needed, `code-review`, and `verification`.
9
+
10
+ Required outcomes:
11
+
12
+ - reproducible symptom or documented reproduction blocker;
13
+ - root cause or clearly bounded remaining hypotheses;
14
+ - smallest safe fix;
15
+ - regression test where practical;
16
+ - exact validation report.
17
+
18
+ Store the investigation and verification under `.maurao/reports/<change-id>-debugging.md` and `.maurao/reports/<change-id>-verification.md` when the host project uses the artifact contract.
19
+
@@ -0,0 +1,35 @@
1
+ ---
2
+ name: feature-development
3
+ description: Deliver a production software feature through specification, implementation, verification, and review.
4
+ ---
5
+
6
+ # Feature Development
7
+
8
+ First classify the work as greenfield, brownfield, or hybrid. For an existing product, use `brownfield-change`; for a new product, use `greenfield-product`. For a focused feature, use the sequence below.
9
+
10
+ 1. `project-discovery` and `technology-discovery`
11
+ 2. `specification` and `requirements`
12
+ 3. `architecture` when boundaries or design decisions are affected
13
+ 4. `planning`
14
+ 5. `testing`
15
+ 6. implementation using the selected technology pack
16
+ 7. `observability` when operational behavior is affected
17
+ 8. `verification`
18
+ 9. `code-review`, `release-readiness`, and `pull-request` as applicable
19
+
20
+ ## Gate conditions
21
+
22
+ - Do not implement while material requirements remain ambiguous.
23
+ - Do not choose a technology pack before `technology-discovery` has recorded evidence.
24
+ - Do not start implementation until the specification and plan are approved for the selected rigor level.
25
+ - Do not mark work complete without running relevant validation.
26
+ - Do not hide unrelated failures introduced or discovered during validation.
27
+ - Keep the final report tied to evidence from the repository and executed checks.
28
+
29
+ ## Required outputs
30
+
31
+ - specification;
32
+ - implementation plan;
33
+ - test plan;
34
+ - verification report;
35
+ - release-readiness report when the change is deliverable.
@@ -0,0 +1,28 @@
1
+ ---
2
+ name: greenfield-product
3
+ description: Shape and deliver a new software product from problem discovery through the first validated vertical slice.
4
+ ---
5
+
6
+ # Greenfield Product
7
+
8
+ Compose `product-discovery`, `requirements`, `technology-discovery`, `architecture`, `planning`, `testing`, `observability`, `verification`, and `release-readiness` as needed.
9
+
10
+ ## Sequence
11
+
12
+ 1. Validate the problem, users, outcome, and non-goals.
13
+ 2. Define the smallest useful product slice.
14
+ 3. Record constraints, risks, and success measures.
15
+ 4. Choose architecture and technology from evidence and expected change.
16
+ 5. Build a vertical slice through the real boundaries.
17
+ 6. Verify behavior and operational readiness.
18
+ 7. Learn from feedback before expanding the product.
19
+
20
+ Do not create speculative infrastructure or broad abstractions before the first slice proves the important assumptions.
21
+
22
+ ## Outputs and gates
23
+
24
+ - Discovery: `.maurao/product-brief.md` approved.
25
+ - Baseline: `.maurao/technology-inventory.md` and `.maurao/system-context.md` available.
26
+ - Specification: requirements and acceptance criteria approved.
27
+ - Delivery: vertical slice verified with an explicit release decision.
28
+
@@ -0,0 +1,6 @@
1
+ # .NET technology pack
2
+
3
+ Inspect the solution, project files, target framework, analyzers, test projects, package versions, and dependency-injection conventions before changing code.
4
+
5
+ Relevant practices: nullable reference types, async cancellation, options validation, structured logging, API contracts, migration safety, and test isolation.
6
+
@@ -0,0 +1,34 @@
1
+ # Java technology pack
2
+
3
+ ## Discovery
4
+
5
+ Inspect `pom.xml`, `build.gradle`, `build.gradle.kts`, `gradlew`, `settings.gradle*`, Java toolchain declarations, module descriptors, test configuration, and CI before changing code.
6
+
7
+ Determine whether the project uses Java, Kotlin, or both, and identify the active build tool: Maven or Gradle. Do not assume Spring just because the project is Java.
8
+
9
+ ## Engineering guidance
10
+
11
+ - Preserve the project's package, module, naming, and dependency-injection conventions.
12
+ - Respect the declared Java toolchain and compiler flags.
13
+ - Handle checked exceptions, resource ownership, interruption, and cancellation intentionally.
14
+ - Avoid blocking calls in reactive or asynchronous code paths.
15
+ - Keep public API and serialization changes backward compatible unless the specification says otherwise.
16
+ - Use immutable values and explicit nullability conventions where the project already supports them.
17
+
18
+ ## Validation discovery
19
+
20
+ Typical commands are project-specific. Prefer the wrapper and scripts committed by the repository:
21
+
22
+ ```text
23
+ ./mvnw test
24
+ ./mvnw verify
25
+ ./gradlew test
26
+ ./gradlew check
27
+ ```
28
+
29
+ Run only commands supported by the project. Inspect profiles, modules, integration-test tasks, and required services before choosing the command.
30
+
31
+ ## Common ecosystems
32
+
33
+ Spring Boot, Jakarta EE, Quarkus, Micronaut, JUnit, TestNG, Mockito, Testcontainers, Hibernate, Flyway, Liquibase, and OpenTelemetry are technology signals—not defaults. Verify their actual presence before loading a specialized skill.
34
+
@@ -0,0 +1,6 @@
1
+ # Node.js technology pack
2
+
3
+ Inspect `package.json`, lockfiles, scripts, TypeScript configuration, test configuration, and runtime version before changing code. Use the repository's package manager and existing conventions.
4
+
5
+ Relevant practices: strict typing, async error handling, input validation, dependency boundaries, test isolation, and structured observability.
6
+
@@ -0,0 +1,6 @@
1
+ # Python technology pack
2
+
3
+ Inspect `pyproject.toml`, lockfiles, supported Python versions, package scripts, test configuration, typing configuration, and lint rules before changing code.
4
+
5
+ Relevant practices: explicit typing, predictable exception handling, resource cleanup, dependency boundaries, deterministic tests, and structured observability.
6
+
@@ -0,0 +1,38 @@
1
+ # Brownfield Map: <system name>
2
+
3
+ ## Baseline evidence
4
+
5
+ - Repositories and branches:
6
+ - Build commands:
7
+ - Test commands:
8
+ - Deployment path:
9
+ - Runtime dependencies:
10
+
11
+ ## Current behavior
12
+
13
+ ### Known behavior
14
+
15
+ -
16
+
17
+ ### Undocumented behavior observed
18
+
19
+ -
20
+
21
+ ## Boundaries and dependencies
22
+
23
+ | Boundary | Evidence | Risk |
24
+ |---|---|---|
25
+ | | | |
26
+
27
+ ## Invariants
28
+
29
+ -
30
+
31
+ ## Change seams
32
+
33
+ Where can the change be made with the smallest blast radius?
34
+
35
+ ## Migration and rollback notes
36
+
37
+ -
38
+
@@ -0,0 +1,36 @@
1
+ # Bug Fix: <short description>
2
+
3
+ ## Symptom
4
+
5
+ What is failing, for whom, and under which conditions?
6
+
7
+ ## Expected behavior
8
+
9
+ What should happen instead?
10
+
11
+ ## Reproduction
12
+
13
+ Steps or a minimal automated reproducer:
14
+
15
+ 1.
16
+
17
+ ## Hypotheses
18
+
19
+ | Hypothesis | Evidence for | Evidence against | Priority |
20
+ |---|---|---|---|
21
+ | | | | High / Medium / Low |
22
+
23
+ ## Root cause
24
+
25
+ Describe the causal chain after confirmation.
26
+
27
+ ## Fix and regression protection
28
+
29
+ - Fix:
30
+ - Regression test:
31
+
32
+ ## Verification
33
+
34
+ - Command:
35
+ - Result:
36
+
@@ -0,0 +1,40 @@
1
+ # Change Proposal: <change name>
2
+
3
+ ## Current state
4
+
5
+ What exists now? Link the system context or brownfield map.
6
+
7
+ ## Desired state
8
+
9
+ What should be different and why?
10
+
11
+ ## Scope and non-goals
12
+
13
+ - In scope:
14
+ - Out of scope:
15
+
16
+ ## Requirements
17
+
18
+ | ID | Requirement | Priority | Source |
19
+ |---|---|---|---|
20
+ | REQ-001 | | Must / Should / May | |
21
+
22
+ ## Compatibility and migration
23
+
24
+ - Backward compatibility:
25
+ - Data migration:
26
+ - Rollout:
27
+ - Rollback:
28
+
29
+ ## Alternatives
30
+
31
+ | Option | Benefits | Costs | Decision |
32
+ |---|---|---|---|
33
+ | | | | |
34
+
35
+ ## Approval gate
36
+
37
+ - Decision owner:
38
+ - Approved:
39
+ - Date:
40
+
@@ -0,0 +1,33 @@
1
+ # Architecture Decision Record: <decision>
2
+
3
+ ## Status
4
+
5
+ Proposed / Accepted / Superseded / Rejected
6
+
7
+ ## Context
8
+
9
+ What decision is required and what constraints matter?
10
+
11
+ ## Decision
12
+
13
+ State the chosen option clearly.
14
+
15
+ ## Alternatives considered
16
+
17
+ -
18
+
19
+ ## Consequences
20
+
21
+ ### Positive
22
+
23
+ -
24
+
25
+ ### Negative or accepted trade-offs
26
+
27
+ -
28
+
29
+ ## Evidence and review date
30
+
31
+ - Evidence:
32
+ - Review when:
33
+
@@ -0,0 +1,50 @@
1
+ # Feature Specification: <feature name>
2
+
3
+ ## Context
4
+
5
+ What problem exists today and who is affected?
6
+
7
+ ## Desired outcome
8
+
9
+ What should be true after this change?
10
+
11
+ ## Scope
12
+
13
+ ### In scope
14
+
15
+ -
16
+
17
+ ### Out of scope
18
+
19
+ -
20
+
21
+ ## Constraints and invariants
22
+
23
+ -
24
+
25
+ ## Requirements
26
+
27
+ ### REQ-001 — <requirement>
28
+
29
+ The system MUST ...
30
+
31
+ ## Acceptance criteria
32
+
33
+ ### AC-001 — <criterion>
34
+
35
+ ```text
36
+ Given <precondition>
37
+ When <action>
38
+ Then <observable result>
39
+ ```
40
+
41
+ ## Risks and open decisions
42
+
43
+ -
44
+
45
+ ## Verification plan
46
+
47
+ | Criterion | Evidence | Status |
48
+ |---|---|---|
49
+ | AC-001 | <test, inspection, or review> | Not verified |
50
+
@@ -0,0 +1,33 @@
1
+ # Implementation Plan: <change name>
2
+
3
+ ## Preconditions
4
+
5
+ - Approved specification:
6
+ - Required decisions:
7
+ - Required access or dependencies:
8
+
9
+ ## Tasks
10
+
11
+ | ID | Task | Depends on | Verification | Done when |
12
+ |---|---|---|---|---|
13
+ | TASK-001 | | | | |
14
+
15
+ ## Test strategy
16
+
17
+ - Unit:
18
+ - Integration:
19
+ - Contract:
20
+ - End-to-end:
21
+ - Manual or exploratory:
22
+
23
+ ## Operational readiness
24
+
25
+ - Logs:
26
+ - Metrics:
27
+ - Traces:
28
+ - Alerts or dashboards:
29
+
30
+ ## Delivery sequence
31
+
32
+ Describe the smallest safe increments and rollback points.
33
+