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.
- package/.clinerules/maurao-method.md +6 -0
- package/.cursor/rules/maurao-method.mdc +7 -0
- package/.github/copilot-instructions.md +6 -0
- package/.github/workflows/ci.yml +39 -0
- package/.github/workflows/publish.yml +32 -0
- package/.github/workflows/release-on-main.yml +87 -0
- package/.maurao/README.md +13 -0
- package/.maurao/config.json +17 -0
- package/AGENTS.md +30 -0
- package/CLAUDE.md +6 -0
- package/GEMINI.md +6 -0
- package/README.md +110 -2
- package/bin/maurao.mjs +218 -0
- package/commands/debug.md +4 -0
- package/commands/discover.md +4 -0
- package/commands/map.md +4 -0
- package/commands/plan.md +4 -0
- package/commands/pr.md +4 -0
- package/commands/review.md +4 -0
- package/commands/specify.md +4 -0
- package/commands/spike.md +4 -0
- package/commands/verify.md +4 -0
- package/docs/artifact-contract.md +22 -0
- package/docs/commands.md +32 -0
- package/docs/method-overview.md +32 -0
- package/docs/npm-release.md +68 -0
- package/docs/portable-adapters.md +26 -0
- package/docs/project-modes.md +33 -0
- package/docs/specification-standard.md +25 -0
- package/docs/tool-support.md +24 -0
- package/docs/workflow.md +45 -0
- package/package.json +42 -4
- package/skills/core/architecture/SKILL.md +16 -0
- package/skills/core/brownfield-analysis/SKILL.md +20 -0
- package/skills/core/debugging/SKILL.md +32 -0
- package/skills/core/planning/SKILL.md +18 -0
- package/skills/core/product-discovery/SKILL.md +20 -0
- package/skills/core/project-discovery/SKILL.md +32 -0
- package/skills/core/requirements/SKILL.md +13 -0
- package/skills/core/specification/SKILL.md +41 -0
- package/skills/core/spike/SKILL.md +30 -0
- package/skills/core/technology-discovery/SKILL.md +43 -0
- package/skills/practices/code-review/SKILL.md +21 -0
- package/skills/practices/data-migration/SKILL.md +14 -0
- package/skills/practices/observability/SKILL.md +28 -0
- package/skills/practices/observability/checklist.md +11 -0
- package/skills/practices/observability/references/dotnet.md +7 -0
- package/skills/practices/observability/references/java.md +9 -0
- package/skills/practices/observability/references/node.md +7 -0
- package/skills/practices/observability/references/python.md +7 -0
- package/skills/practices/observability/templates/logging-plan.md +16 -0
- package/skills/practices/observability/templates/metrics-plan.md +6 -0
- package/skills/practices/observability/templates/tracing-plan.md +14 -0
- package/skills/practices/pull-request/SKILL.md +17 -0
- package/skills/practices/release-readiness/SKILL.md +20 -0
- package/skills/practices/security/SKILL.md +11 -0
- package/skills/practices/testing/SKILL.md +37 -0
- package/skills/practices/verification/SKILL.md +15 -0
- package/skills/workflows/brownfield-change/SKILL.md +26 -0
- package/skills/workflows/bug-fix/SKILL.md +19 -0
- package/skills/workflows/feature-development/SKILL.md +35 -0
- package/skills/workflows/greenfield-product/SKILL.md +28 -0
- package/technology-packs/dotnet/README.md +6 -0
- package/technology-packs/java/README.md +34 -0
- package/technology-packs/node/README.md +6 -0
- package/technology-packs/python/README.md +6 -0
- package/templates/brownfield-map.md +38 -0
- package/templates/bug-fix.md +36 -0
- package/templates/change-proposal.md +40 -0
- package/templates/decision-record.md +33 -0
- package/templates/feature-spec.md +50 -0
- package/templates/implementation-plan.md +33 -0
- package/templates/product-brief.md +41 -0
- package/templates/pull-request.md +27 -0
- package/templates/spike-report.md +36 -0
- package/templates/system-context.md +36 -0
- package/templates/technology-inventory.md +38 -0
- package/templates/test-plan.md +23 -0
- package/templates/threat-model.md +31 -0
- 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,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
|
+
|