ma-agents 3.6.2 → 3.9.0

package/_bmad-output/implementation-artifacts/done/2-2-csharp-coding-standards-skill.md

@@ -1,211 +0,0 @@
-# Story 2.2: Create C# Best Practices Skill
-
-Status: done
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **C# engineer**,
-I want a C# coding standards and best practices skill available in ma-agents,
-So that my AI coding agent follows our organization's C# methodology consistently.
-
-## Acceptance Criteria
-
-1. **Given** the C# skill directory exists at `skills/csharp-best-practices/`
-   **When** the skill is listed via `npx ma-agents list`
-   **Then** it appears with description referencing C# standards and tags including "csharp"
-   **And** `skill.json` contains valid metadata including `applies_when` conditions for C#/.NET contexts
-
-2. **Given** the C# skill is installed to any supported agent
-   **When** the agent receives the skill content
-   **Then** it contains C# coding standards, .NET patterns, async/await best practices, and LINQ guidelines
-   **And** the content covers modern C# language features (C# 10+) applicable to .NET 6 through .NET 8+
-
-3. **Given** the skill follows the standard skill schema contract
-   **When** installed across multiple agents
-   **Then** the installed content is identical across all target agents (SKILL.md fallback, no agent-specific templates)
-   **And** content is language-focused, not agent-specific (FR36)
-
-## Tasks / Subtasks
-
-- [x] Task 1: Create skill directory and metadata (AC: #1)
-  - [x] 1.1: Create directory `skills/csharp-best-practices/`
-  - [x] 1.2: Create `skill.json` with all required fields (see skill.json Schema section below). Must include `applies_when` array for skill discovery and `always_load: true` (this is the only C# skill — it must auto-load in C# contexts).
-  - [x] 1.3: Verify `npx ma-agents list` shows the new skill with correct metadata
-- [x] Task 2: Author SKILL.md content (AC: #2)
-  - [x] 2.1: Write C# coding standards covering: naming conventions (PascalCase types/methods, camelCase locals/params, _camelCase private fields), code organization (namespace per folder, one type per file). Target practical density — prioritize high-value rules over exhaustive coverage. If content naturally exceeds 500 lines, use `references/` directory for supplementary material.
-  - [x] 2.2: Include async/await best practices: async all the way, avoid async void (except event handlers), ConfigureAwait guidance, cancellation token propagation, ValueTask vs Task guidance
-  - [x] 2.3: Include LINQ guidelines: when to use query vs method syntax, deferred execution awareness, materialization points, performance considerations for large collections
-  - [x] 2.4: Include modern C# language features (C# 10/11/12): primary constructors, collection expressions, raw string literals, required members, file-scoped types, global usings, nullable reference types (NRT) enforcement. Note: these features span .NET 6–8 — scope is "modern C#" not strictly ".NET 8 only."
-  - [x] 2.5: Include error handling patterns: exception hierarchy, Result pattern, problem details for APIs, global exception handling middleware
-  - [x] 2.6: Include dependency injection overview: constructor injection, service lifetimes (Singleton/Scoped/Transient). Keep to language-level patterns only — defer framework-specific DI patterns (IOptions, keyed services, middleware) to a future `csharp-aspnet-patterns` skill to avoid overlap.
-  - [x] 2.7: Include testing patterns: Arrange-Act-Assert structure, framework-agnostic conventions. Present xUnit as one common choice but acknowledge MSTest and NUnit as alternatives. Avoid prescribing specific assertion or mocking libraries — mention FluentAssertions, NSubstitute, Moq as popular options without mandating them.
-  - [x] 2.8: Optionally create `examples/` directory with representative code samples, consistent with peer language skills
-- [x] Task 3: Verify installation across agents (AC: #3)
-  - [x] 3.1: Install to at least 2 different agents (e.g., claude-code and cursor)
-  - [x] 3.2: Verify installed content is identical across agents (SKILL.md fallback is the only path)
-  - [x] 3.3: Verify `generateSkillsManifest()` produces correct MANIFEST.yaml entries — check that `applies_when` conditions and `always_load` flag are present in the generated manifest
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **Skill schema contract:** Every skill MUST have `skill.json` (metadata SSoT) + `SKILL.md` (canonical content). Optional directories: `examples/`, `references/`, `scripts/`, `hooks/`, `assets/`. [Source: architecture.md#Data-Architecture]
-- **Directory naming:** `kebab-case` for skill directories [Source: architecture.md#Naming-Patterns]
-- **No installer changes needed:** Adding a new skill requires ONLY the skill package files — the installer discovers skills by scanning the `skills/` directory via `listSkills()`. [Source: architecture.md#Extensibility-Model, NFR14]
-- **Template resolution:** `<agent-name>.md` (highest) -> `generic.md` -> `SKILL.md` (lowest/fallback). Templates are flat files at the skill root — there is NO `templates/` subdirectory. For this skill, `SKILL.md` alone is sufficient.
-
-### Greenfield — No Existing C# Skills
-
-Unlike C++ (6 existing domain skills) and Python (2 existing domain skills), **no C# skills currently exist** in the library. This skill is the first C# entry.
-
-**Implications of being the only C# skill:**
-- It must be self-contained — no sibling skills to cross-reference. Content should be more detailed than the C++ umbrella skill which can defer to 6 companions.
-- `always_load: true` is important — without it, and without other C# skills, there is no C# guidance unless the developer explicitly requests it.
-- Scope boundaries should be drawn clearly for future skills. This skill covers **language-level** patterns. Framework-specific patterns (ASP.NET Core middleware, EF Core, Blazor, etc.) should be deferred to future skills like `csharp-aspnet-patterns` or `csharp-ef-core`.
-
-### skill.json Schema
-
-Follow the pattern from existing skills. The `applies_when` field is **critical** — it tells the manifest generator and planning instruction when to load this skill:
-```json
-{
-  "name": "C# Best Practices",
-  "description": "Comprehensive C# coding standards covering modern C# (C# 10-12), async/await, LINQ, dependency injection basics, nullable reference types, and testing conventions.",
-  "version": "1.0.0",
-  "author": "ma-agents",
-  "tags": ["csharp", "c#", "dotnet", ".net", "coding-standards", "best-practices", "net8"],
-  "applies_when": [
-    "writing c# code",
-    "creating new c# files or classes",
-    "reviewing c# code style or conventions",
-    "working with .net projects",
-    "setting up a c# project"
-  ],
-  "always_load": true
-}
-```
-
-**Note on `category` field:** Omitted — no existing skill uses it, and `listSkills()` doesn't read or filter by it. Can be backfilled if category support is added later.
-
-**Note on `always_load: true`:** As the only C# skill in the library, this must auto-load. Without it, AI agents have no C# guidance unless the developer knows to request it by name. This matches the pattern of other "primary" language skills like `cmake-best-practices` and `cpp-modern-composition`.
-
-### SKILL.md Content Pattern
-
-Follow the **policy-based pattern** used by existing language skills:
-- Lead with language context and scope — specify "modern C# (C# 10+)" rather than ".NET 8+" to match the actual feature coverage
-- Use numbered policies with **Rule** -> **Action** format
-- Include tables for naming convention mappings (see Naming Convention Table below)
-- Consider creating an `examples/` directory with representative code samples, consistent with peer language skills
-- Target practical density — if content exceeds 500 lines, split supplementary material to `references/`
-- **No YAML frontmatter** — metadata comes from skill.json only
-
-### Modern C# Coverage Priorities
-
-The skill covers **modern C# language features** across recent .NET versions. The scope is "modern C#" (C# 10+), not strictly ".NET 8 only":
-
-**C# 12 (.NET 8):** Primary constructors, collection expressions (`[1, 2, 3]`), default lambda parameters, alias any type, inline arrays
-**C# 11 (.NET 7):** Raw string literals, required members, file-scoped types, generic math, list patterns
-**C# 10 (.NET 6):** Global usings, file-scoped namespaces, record structs, extended property patterns
-**Foundational:** Nullable reference types (NRT), pattern matching, records, init-only properties, top-level statements
-
-**Language-level framework patterns (include):** System.Text.Json, IHttpClientFactory, basic DI (constructor injection, service lifetimes)
-**Framework-specific patterns (defer to future skills):** Minimal APIs, middleware pipelines, IOptions/IOptionsSnapshot, Health Checks, OpenTelemetry, EF Core — these belong in a future `csharp-aspnet-patterns` or `csharp-ef-core` skill
-
-### Naming Convention Table
-
-Include a comprehensive naming table — this is the highest-value section for AI agents:
-
-| Element | Convention | Example |
-|---------|-----------|---------|
-| Namespace | PascalCase, match folder | `MyApp.Services` |
-| Class/Struct/Record | PascalCase | `CustomerService` |
-| Interface | IPascalCase | `ICustomerService` |
-| Method | PascalCase | `GetCustomerAsync` |
-| Property | PascalCase | `FirstName` |
-| Local variable | camelCase | `customerCount` |
-| Parameter | camelCase | `customerId` |
-| Private field | _camelCase | `_logger` |
-| Constant | PascalCase | `MaxRetryCount` |
-| Enum | PascalCase (singular) | `OrderStatus` |
-| Async method | suffix `Async` | `SaveAsync` |
-
-### Testing Patterns — Framework Agnosticism
-
-Task 2.7 covers testing patterns. This is an area where opinionated prescriptions cause problems — many C# teams use different frameworks. The SKILL.md should:
-- Present **Arrange-Act-Assert** as the universal pattern
-- Mention xUnit, NUnit, and MSTest as the three major frameworks without mandating one
-- Reference FluentAssertions, Shouldly, NSubstitute, Moq as popular options, not requirements
-- Focus on test structure, naming conventions, and practices that are framework-agnostic
-
-### Critical Guardrails
-
-- **No installer code changes** — only skill package files [Source: architecture.md, NFR14]
-- **kebab-case** directory name: `csharp-best-practices` [Source: architecture.md#Naming-Patterns]
-- **snake_case** keys in skill.json [Source: architecture.md#JSON/YAML-Fields]
-- **No emoji** in SKILL.md content [Source: architecture.md#Format-Patterns]
-- **Cross-agent equivalence** — content must be language-focused, not agent-specific (FR36)
-- **Must include `applies_when`** in skill.json — without it, the skill won't appear in generated MANIFEST.yaml with load conditions, making it invisible to automatic skill selection
-- **Language vs. framework boundary** — keep DI, error handling, and testing content at the language level. Defer ASP.NET Core middleware, EF Core, Blazor patterns to future skills.
-
-### Project Structure Notes
-
-- New directory: `skills/csharp-best-practices/`
-- New files: `skill.json`, `SKILL.md`
-- Optional: `examples/` directory for representative code samples
-- Optional: `references/` directory if content exceeds 500 lines
-- No changes to any existing files or modules
-
-### References
-
-- [Source: _bmad-output/planning-artifacts/epics.md#Epic-2] — Story 2.2 definition and acceptance criteria
-- [Source: _bmad-output/planning-artifacts/prd.md#FR36] — FR36: Functionally equivalent behavior across agents
-- [Source: _bmad-output/planning-artifacts/prd.md#FR39] — FR39: Skill authoring format
-- [Source: _bmad-output/planning-artifacts/architecture.md#Data-Architecture] — Skill schema contract
-- [Source: _bmad-output/planning-artifacts/architecture.md#Extensibility-Model] — Template resolution priority
-- [Source: _bmad-output/planning-artifacts/architecture.md#Naming-Patterns] — Naming conventions
-- [Source: skills/python-security-skill/] — Representative policy-based skill pattern (includes applies_when)
-- [Source: skills/cpp-memory-handling/] — Representative language skill structure (includes applies_when, examples/)
-- [Source: lib/installer.js `function listSkills`] — Skill discovery mechanism
-- [Source: lib/installer.js `function generateSkillsManifest`] — MANIFEST.yaml generation (consumes applies_when, always_load)
-
-## Dev Agent Record
-
-### Agent Model Used
-
-claude-sonnet-4-6
-
-### Debug Log References
-
-None — implementation was straightforward skill package authoring.
-
-### Completion Notes List
-
-- Created `skills/csharp-best-practices/skill.json` with all required fields: name, description, version, author, tags (including "csharp"), applies_when (5 conditions), always_load: true.
-- Created `skills/csharp-best-practices/SKILL.md` covering: naming conventions table, code organization, nullable reference types, modern C# features (primary constructors, collection expressions, raw strings, pattern matching, records and record structs, file-scoped types), async/await, LINQ, error handling (Result pattern + exception hierarchy), dependency injection (service lifetimes), and testing (AAA pattern, framework-agnostic).
-- Skipped `examples/` directory (task 2.8 was optional; SKILL.md code blocks are sufficient for AI agent consumption).
-- Task 2.5 (error handling): Global exception handling middleware is explicitly deferred to a future `csharp-aspnet-patterns` skill — it is an ASP.NET Core framework-specific pattern, not a language-level concern. The language-level obligation (ensuring exceptions carry sufficient data to produce a ProblemDetails response) is covered in Section 7.
-- Installed to claude-code agent: `.claude/skills/csharp-best-practices/SKILL.md` and updated MANIFEST.yaml.
-- Installed to cursor agent: `.cursor/skills/csharp-best-practices/SKILL.md` and updated MANIFEST.yaml.
-- Verified installed content is byte-for-byte identical across both agents (SKILL.md fallback path only).
-- Verified generated MANIFEST.yaml entries include `applies_when` conditions and `always_load: true`.
-- All 9 existing regression tests passed.
-- **Code review fixes applied (2026-03-19):** Added Section 4.6 (file-scoped types, C# 11 `file` modifier); expanded Section 4.5 to cover `record struct` and `readonly record struct`; replaced EF Core `FirstOrDefaultAsync` in async example with framework-agnostic `_repository.GetByIdAsync`; replaced ASP.NET Core `builder.Services` in DI example with `IServiceCollection`; clarified Section 7 middleware deferral boundary.
-
-### File List
-
-- skills/csharp-best-practices/skill.json (new)
-- skills/csharp-best-practices/SKILL.md (new)
-- .claude/skills/csharp-best-practices/SKILL.md (new — installed)
-- .claude/skills/MANIFEST.yaml (modified — new entry added)
-- .claude/CLAUDE.md (modified — planning instruction updated)
-- .cursor/skills/csharp-best-practices/SKILL.md (new — installed)
-- .cursor/skills/MANIFEST.yaml (modified — new entry added)
-- .cursor/cursor.md (modified — planning instruction updated)
-- _bmad-output/implementation-artifacts/sprint-status.yaml (modified — status updated)
-- _bmad-output/implementation-artifacts/2-2-csharp-coding-standards-skill.md (modified — tasks checked, status updated)
-
-### Change Log
-
-- 2026-03-19: Implemented Story 2.2 — Created C# Best Practices skill package (`skill.json` + `SKILL.md`), installed to claude-code and cursor agents, verified cross-agent content equivalence and MANIFEST.yaml generation.
-- 2026-03-19: Code review fixes — Added file-scoped types (§4.6), record struct guidance (§4.5), replaced framework-coupled code examples in §5 and §8, documented middleware deferral in §7 and completion notes.

package/_bmad-output/implementation-artifacts/done/2-3-python-coding-standards-skill.md

@@ -1,189 +0,0 @@
-# Story 2.3: Create Python Best Practices Skill
-
-Status: done
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **Python engineer**,
-I want a Python coding standards and best practices skill available in ma-agents,
-So that my AI coding agent follows our organization's Python methodology consistently.
-
-## Acceptance Criteria
-
-1. **Given** the Python skill directory exists at `skills/python-best-practices/`
-   **When** the skill is listed via `npx ma-agents list`
-   **Then** it appears with category "language" and description referencing Python standards
-
-2. **Given** the Python skill is installed to any supported agent
-   **When** the agent receives the skill content
-   **Then** it contains Python coding standards, PEP 8 conventions, type hinting patterns, and packaging best practices
-   **And** the content covers Python 3.10+ modern patterns
-
-3. **Given** all three language skills (C++, C#, Python) are installed
-   **When** the manifest is checked via `npx ma-agents status`
-   **Then** all three appear with correct versions and installation status per agent
-
-## Tasks / Subtasks
-
-- [x] Task 1: Create skill directory and metadata (AC: #1)
-  - [x] 1.1: Create directory `skills/python-best-practices/`
-  - [x] 1.2: Create `skill.json` with: name "Python Best Practices", version "1.0.0", category "language", description referencing Python coding standards for 3.10+, author "ma-agents", tags ["python", "coding-standards", "best-practices", "pep8", "type-hints"], always_load false
-  - [x] 1.3: Verify `npx ma-agents list` shows the new skill with correct metadata
-- [x] Task 2: Author SKILL.md content (AC: #2)
-  - [x] 2.1: Write comprehensive Python coding standards covering: PEP 8 naming conventions (snake_case functions/variables, PascalCase classes, UPPER_SNAKE constants), code organization (module structure, `__init__.py` patterns, `__all__` exports)
-  - [x] 2.2: Include type hinting patterns: function annotations, variable annotations, generics (`list[str]` not `List[str]` for 3.10+), `TypeAlias`, `TypeVar`, `Protocol`, `ParamSpec`, `TypeGuard`, `Self` (3.11), `type` statement (3.12)
-  - [x] 2.3: Include modern Python patterns: structural pattern matching (`match/case` 3.10), exception groups and `except*` (3.11), f-string improvements (3.12), `__slots__` usage, dataclasses vs attrs vs Pydantic guidance, walrus operator (`:=`)
-  - [x] 2.4: Include packaging best practices: `pyproject.toml` (not setup.py), dependency management (pip-tools, poetry, uv), virtual environments, `src/` layout convention
-  - [x] 2.5: Include async patterns: `asyncio` conventions, `async for`/`async with`, `TaskGroup` (3.11), structured concurrency, avoid mixing sync and async
-  - [x] 2.6: Cross-reference existing Python skills where they provide deeper coverage (see Dev Notes)
-- [x] Task 3: Verify installation across agents and manifest status (AC: #2, #3)
-  - [x] 3.1: Install to at least 2 different agents (e.g., claude-code and cursor)
-  - [x] 3.2: Verify SKILL.md fallback works when no agent-specific template exists
-  - [x] 3.3: Install all 3 language skills (cpp-best-practices, csharp-best-practices, python-best-practices) and verify `npx ma-agents status` shows all three with correct versions
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **Skill schema contract:** Every skill MUST have `skill.json` (metadata SSoT) + `SKILL.md` (canonical content). No other files are required. [Source: architecture.md#Data-Architecture]
-- **Directory naming:** `kebab-case` for skill directories [Source: architecture.md#Naming-Patterns]
-- **No installer changes needed:** Adding a new skill requires ONLY the skill package files — the installer discovers skills by scanning the directory. [Source: architecture.md#Extensibility-Model, NFR14]
-- **Template resolution:** `templates/<agent-name>.md` -> `templates/generic.md` -> `SKILL.md` (fallback). For this skill, `SKILL.md` alone is sufficient.
-
-### Relationship to Existing Python Skills
-
-2 domain-specific Python skills already exist in the library:
-
-| Existing Skill | Focus | Relationship |
-|---------------|-------|-------------|
-| `python-security-skill` | OWASP 2025 aligned security (always_load: true) | Deep-dive on security — cross-reference from best-practices |
-| `python-dependency-mgmt` | Dependency/supply chain security | Deep-dive on dependency security — cross-reference |
-
-**This skill is the umbrella** — it covers broad Python coding standards, type hinting, modern patterns, and packaging, while referencing the security-focused skills for deeper coverage. It should NOT duplicate content from existing skills. Use cross-references like:
-```markdown
-> For Python security best practices (OWASP 2025), see the `python-security-skill`.
-> For dependency security and supply chain protection, see the `python-dependency-mgmt` skill.
-```
-
-### skill.json Schema
-
-```json
-{
-  "name": "Python Best Practices",
-  "description": "Comprehensive Python coding standards covering PEP 8 conventions, type hinting (3.10+), modern patterns (match/case, exception groups), async, and packaging best practices. Cross-references security-focused Python skills.",
-  "version": "1.0.0",
-  "category": "language",
-  "author": "ma-agents",
-  "tags": ["python", "coding-standards", "best-practices", "pep8", "type-hints", "python3.10", "python3.11", "python3.12"],
-  "always_load": false
-}
-```
-
-### SKILL.md Content Pattern
-
-Follow the **policy-based pattern** used by existing Python skills (e.g., `python-security-skill/SKILL.md`):
-- Lead with language context and Python version scope (3.10+)
-- Use numbered policies with **Rule** -> **Action** format
-- Include tables for naming convention mappings and modern pattern guidance
-- Cross-reference sibling Python skills
-- Keep under 500 lines — split to `references/` if needed
-- **No YAML frontmatter** — metadata comes from skill.json only
-
-### Python 3.10+ Coverage Priorities
-
-The skill must cover **Python 3.10+ modern patterns** per AC #2:
-
-**Python 3.10:** Structural pattern matching (`match/case`), `ParamSpec`, `TypeAlias`, union types with `X | Y` syntax, `TypeGuard`
-**Python 3.11:** Exception groups (`ExceptionGroup`, `except*`), `Self` type, `TaskGroup` for structured concurrency, `tomllib`, `StrEnum`
-**Python 3.12:** `type` statement for type aliases, f-string improvements (nested quotes, backslashes), `@override` decorator, per-interpreter GIL (awareness)
-**Python 3.13 (awareness):** Free-threaded mode (`--disable-gil`), improved error messages — mention as forward-looking but don't make it a requirement
-
-### Type Hinting Evolution Table
-
-Include a version-aware type hinting table — high value for AI agents:
-
-| Pattern | Old (pre-3.10) | Modern (3.10+) |
-|---------|---------------|----------------|
-| Union types | `Union[str, int]` | `str \| int` |
-| Optional | `Optional[str]` | `str \| None` |
-| List type | `List[str]` | `list[str]` |
-| Dict type | `Dict[str, int]` | `dict[str, int]` |
-| Tuple type | `Tuple[str, ...]` | `tuple[str, ...]` |
-| Type alias | `MyType = list[str]` | `type MyType = list[str]` (3.12) |
-
-### Packaging Guidance: Modern Stack
-
-The packaging section should recommend the modern toolchain:
-- **`pyproject.toml`** over `setup.py`/`setup.cfg` — PEP 621 compliant
-- **`uv`** as the recommended fast package manager (Astral, Rust-based)
-- **`src/` layout** as the default project structure
-- **`ruff`** for linting and formatting (replaces flake8 + black + isort)
-- **`mypy` or `pyright`** for type checking
-
-### Critical Guardrails
-
-- **No installer code changes** — only skill package files [Source: architecture.md, NFR14]
-- **kebab-case** directory name: `python-best-practices` [Source: architecture.md#Naming-Patterns]
-- **snake_case** keys in skill.json [Source: architecture.md#JSON/YAML-Fields]
-- **No emoji** in SKILL.md content [Source: architecture.md#Format-Patterns]
-- **Do not duplicate** content from existing Python skills — cross-reference instead
-- **Cross-agent equivalence** — content must be language-focused, not agent-specific (FR36)
-
-### AC #3: Cross-Skill Manifest Verification
-
-This story's AC #3 is a cross-cutting acceptance criterion that validates all 3 Epic 2 skills together. It should be tested AFTER stories 2-1 and 2-2 are also complete. If implementing stories in order, this AC can only be fully verified as the last step of story 2-3. If stories are implemented in parallel, coordinate manifest verification at the end.
-
-### Project Structure Notes
-
-- New directory: `skills/python-best-practices/`
-- New files: `skill.json`, `SKILL.md`
-- Optional: `references/` directory if content exceeds 500 lines
-- No changes to any existing files or modules
-
-### References
-
-- [Source: _bmad-output/planning-artifacts/epics.md#Epic-2] — Story 2.3 definition and acceptance criteria
-- [Source: _bmad-output/planning-artifacts/prd.md#FR36] — FR36: Functionally equivalent behavior across agents
-- [Source: _bmad-output/planning-artifacts/prd.md#FR39] — FR39: Skill authoring format
-- [Source: _bmad-output/planning-artifacts/architecture.md#Data-Architecture] — Skill schema contract
-- [Source: _bmad-output/planning-artifacts/architecture.md#Extensibility-Model] — Template resolution priority
-- [Source: _bmad-output/planning-artifacts/architecture.md#Naming-Patterns] — Naming conventions
-- [Source: skills/python-security-skill/] — Existing Python security skill (cross-reference target)
-- [Source: skills/python-dependency-mgmt/] — Existing Python dependency skill (cross-reference target)
-
-## Dev Agent Record
-
-### Agent Model Used
-
-claude-sonnet-4-6
-
-### Debug Log References
-
-No debug issues encountered. Implementation was straightforward: two files only, no installer changes.
-
-### Completion Notes List
-
-- Created `skills/python-best-practices/skill.json` with correct metadata matching schema from Dev Notes: category "language", always_load false, 8 tags covering python/pep8/type-hints and version tags.
-- Created `skills/python-best-practices/SKILL.md` (~350 lines, under 500-line limit) covering all 6 subtask areas: PEP 8 naming (section 1), code organization (section 2), type hinting with version table and advanced constructs (section 3), modern patterns — match/case, except*, f-strings, walrus, __slots__, dataclasses guidance (section 4), async patterns with TaskGroup (section 5), packaging with pyproject.toml + uv + ruff + src/ layout (section 6), 3.13 forward-looking awareness (section 7), and cross-references to sibling Python skills.
-- SKILL.md uses no emoji (per architecture guardrail), no YAML frontmatter, and follows the policy-based Rule/Action pattern from existing Python skills. Installed copies have installer-injected frontmatter (systemic behavior — all peer skills have it too).
-- Verified `npx ma-agents list` shows skill with correct description (AC #1).
-- Installed to claude-code and cursor agents; SKILL.md fallback confirmed (no agent-specific templates needed) (AC #2, 3.1, 3.2).
-- Verified `npx ma-agents status` shows all three language skills (cpp-best-practices, csharp-best-practices, python-best-practices) at v1.0.0 installed (AC #3).
-
-### File List
-
-- `skills/python-best-practices/skill.json` (new)
-- `skills/python-best-practices/SKILL.md` (new)
-- `.claude/skills/python-best-practices/SKILL.md` (new — installed artifact)
-- `.claude/skills/MANIFEST.yaml` (modified — updated by installer)
-- `.claude/CLAUDE.md` (modified — updated by installer)
-- `.cursor/skills/python-best-practices/SKILL.md` (new — installed artifact)
-- `.cursor/skills/MANIFEST.yaml` (modified — updated by installer)
-- `.cursor/cursor.md` (modified — updated by installer)
-
-## Change Log
-
-- 2026-03-19: Story 2.3 implemented — created Python Best Practices skill package (`skill.json` + `SKILL.md`), installed to claude-code and cursor agents, verified all 3 Epic 2 language skills in `npx ma-agents status`.
-- 2026-03-19: Code review fixes: async example bug (H2 — `open(path)` replaced with `Path(path).read_text` in `asyncio.to_thread`), MANIFEST `always_load: false` added to both agent MANIFESTs (H1), M3 coverage additions (`StrEnum`, `tomllib`, `@override` in new section 4.7), L1 virtual environments section added (section 6.4, `uv venv` / `.venv`), L2 walrus operator comment fixed ("Without walrus" → "With walrus — single call"). Installed copies synced. M1 completion note updated to reflect installer-injected frontmatter as systemic behavior.

package/_bmad-output/implementation-artifacts/done/3-1-skill-scaffolding-tool.md

@@ -1,184 +0,0 @@
-# Story 3.1: Skill Scaffolding Command
-
-Status: review
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **Chief Architect**,
-I want to run `npx ma-agents create-skill <skill-name>` to generate a new skill directory with all required files,
-So that I can author new skills quickly without manually creating the directory structure.
-
-## Acceptance Criteria
-
-1. **Given** the user runs `npx ma-agents create-skill my-new-skill`
-   **When** the command executes
-   **Then** a directory `skills/my-new-skill/` is created with:
-   - `skill.json` populated with name, version "1.0.0", empty description, default category, empty tags, `always_load: false`
-   - `SKILL.md` with a template structure including placeholder content sections
-   - `templates/` directory (empty, ready for agent-specific templates)
-   - `references/` directory (empty)
-   - `assets/` directory (empty)
-
-2. **Given** a skill with the same name already exists
-   **When** the create-skill command is run
-   **Then** the command fails with an error message and does not overwrite the existing skill
-   **And** a hint suggests using a different name or removing the existing skill first
-
-3. **Given** the skill name contains invalid characters (spaces, uppercase, special chars)
-   **When** the create-skill command is run
-   **Then** the command fails with an error explaining kebab-case naming requirement
-
-## Tasks / Subtasks
-
-- [x] Task 1: Add `create-skill` command to CLI router (AC: #1, #2, #3)
-  - [x] 1.1: Add `create-skill` to the command routing in `bin/cli.js` (search: command routing logic, likely a switch/if-else block handling `install`, `list`, `status`, `uninstall`)
-  - [x] 1.2: Create handler function `handleCreateSkill(args)` in `bin/cli.js` or a new `lib/skill-authoring.js` module (see Dev Notes on module placement)
-  - [x] 1.3: Add `create-skill` to help text (search: `console.log.*Usage`)
-- [x] Task 2: Implement name validation (AC: #3)
-  - [x] 2.1: Validate skill name matches kebab-case pattern: `/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/`
-  - [x] 2.2: On invalid name: print `Error: Skill name must be kebab-case (lowercase letters, numbers, hyphens)` / `Hint: Example: my-new-skill, python-linting, api-security`
-  - [x] 2.3: Exit with code 1 on validation failure
-- [x] Task 3: Implement duplicate detection (AC: #2)
-  - [x] 3.1: Check if `skills/<skill-name>/` directory already exists
-  - [x] 3.2: On duplicate: print `Error: Skill '<skill-name>' already exists at skills/<skill-name>/` / `Hint: Choose a different name or remove the existing skill first`
-  - [x] 3.3: Exit with code 1 on duplicate
-- [x] Task 4: Generate skill directory and files (AC: #1)
-  - [x] 4.1: Create `skills/<skill-name>/` directory
-  - [x] 4.2: Generate `skill.json` with template values:
-    ```json
-    {
-      "name": "<Skill Name from kebab>",
-      "description": "",
-      "version": "1.0.0",
-      "category": "workflow",
-      "author": "ma-agents",
-      "tags": [],
-      "always_load": false
-    }
-    ```
-    Convert kebab-case to Title Case for the name field (e.g., `my-new-skill` -> `My New Skill`)
-  - [x] 4.3: Generate `SKILL.md` with template structure (see Dev Notes for template content)
-  - [x] 4.4: Create empty directories: `templates/`, `references/`, `assets/`
-  - [x] 4.5: Print success message: `Skill '<skill-name>' created at skills/<skill-name>/`
-  - [x] 4.6: Print next steps hint: `  Next: Edit skill.json and SKILL.md to add your skill content`
-- [x] Task 5: Test the command
-  - [x] 5.1: Run `npx ma-agents create-skill test-skill` and verify all files/dirs created
-  - [x] 5.2: Run `npx ma-agents create-skill test-skill` again and verify duplicate error
-  - [x] 5.3: Run `npx ma-agents create-skill InvalidName` and verify kebab-case error
-  - [x] 5.4: Run `npx ma-agents list` and verify new skill appears
-  - [x] 5.5: Clean up test skill directory after testing
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **Command routing:** New commands are added to the CLI router in `bin/cli.js`. The router dispatches to handler functions. [Source: architecture.md#Module-Boundaries]
-- **Module placement decision:** This command primarily creates files on disk. Two options:
-  1. **Inline in cli.js** — if the logic is <50 lines, keep it in cli.js as a handler function (simpler, follows existing pattern for simple commands)
-  2. **New module `lib/skill-authoring.js`** — if the logic grows beyond scaffolding (validation, test-install in stories 3-2/3-3), create a new module. The 4-module architecture allows new modules when genuinely needed. [Source: architecture.md#Enforcement-Guidelines]
-  **Recommendation:** Create `lib/skill-authoring.js` since Epic 3 has multiple skill authoring commands that share context. This keeps cli.js as a thin router.
-- **File operations:** Use `fs.mkdirSync` with `{ recursive: true }` for directory creation. Use `path.join()` for all paths. [Source: architecture.md#Enforcement-Guidelines]
-- **No new dependencies:** Use Node.js built-in `fs` and `path` only.
-
-### SKILL.md Template Content
-
-The generated SKILL.md should provide a useful starting structure:
-
-```markdown
-# <Skill Name>
-
-<Brief description of what this skill does and when it applies.>
-
-## Policies
-
-### 1. <First Policy>
-
-**Rule:** <What the agent must do or not do>
-
-**Action:**
-- <Specific instruction>
-- <Specific instruction>
-
-### 2. <Second Policy>
-
-**Rule:** <What the agent must do or not do>
-
-**Action:**
-- <Specific instruction>
-
-## References
-
-- <Link to any supporting documents in references/ directory>
-```
-
-This matches the policy-based pattern used by existing skills (e.g., `cpp-memory-handling`, `python-security-skill`).
-
-### skill.json Default Category
-
-The architecture specifies valid categories: `security|architecture|testing|documentation|workflow|language`. Default to `"workflow"` as the most generic category. The author will change it to the appropriate category.
-
-### Kebab-to-Title Conversion
-
-For the `name` field in skill.json, convert kebab-case to Title Case:
-- `my-new-skill` -> `My New Skill`
-- `python-best-practices` -> `Python Best Practices`
-- `api-security` -> `Api Security`
-
-Simple implementation: `name.split('-').map(w => w[0].toUpperCase() + w.slice(1)).join(' ')`
-
-### Critical Guardrails
-
-- **Use `path.join()` for all file paths** [Source: architecture.md#Enforcement-Guidelines]
-- **No new npm dependencies** [Source: architecture.md#Anti-Patterns]
-- **Error format:** `Error: <what>` then `  Hint: <how to fix>` [Source: architecture.md#Format-Patterns]
-- **Console output:** plain text, chalk colors, no emoji [Source: architecture.md#Format-Patterns]
-- **File naming:** `kebab-case` for directories, `snake_case` for skill.json keys [Source: architecture.md#Naming-Patterns]
-
-### Project Structure Notes
-
-- Files to modify: `bin/cli.js` (add command route)
-- Files to create: `lib/skill-authoring.js` (new module for skill authoring commands)
-- No changes to existing skills, installer, or agents modules
-
-### References
-
-- [Source: _bmad-output/planning-artifacts/epics.md#Epic-3] — Story 3.1 definition
-- [Source: _bmad-output/planning-artifacts/prd.md#FR39] — FR39: Skill authoring format
-- [Source: _bmad-output/planning-artifacts/architecture.md#Skill-Directory-Structure] — Mandatory skill structure
-- [Source: _bmad-output/planning-artifacts/architecture.md#Data-Architecture] — Skill schema contract
-- [Source: _bmad-output/planning-artifacts/architecture.md#Naming-Patterns] — Naming conventions
-- [Source: _bmad-output/planning-artifacts/architecture.md#Format-Patterns] — Console output and error format
-- [Source: skills/skill-creator/SKILL.md] — Existing skill-creator skill (reference for authoring guidance)
-
-## Dev Agent Record
-
-### Agent Model Used
-
-claude-sonnet-4-6
-
-### Debug Log References
-
-None — implementation was straightforward.
-
-### Completion Notes List
-
-- Created `lib/skill-authoring.js` with `validateSkillName`, `createSkill`, `handleCreateSkill`, `kebabToTitleCase` exports
-- Added `create-skill` command routing to `bin/cli.js` switch statement
-- Added `create-skill` to help text in `showHelp()`
-- Created `test/skill-authoring.test.js` with 14 tests: 6 unit tests for `validateSkillName`, 8 integration CLI tests covering all ACs
-- All 14 new tests pass; all 58 existing regression tests pass (no regressions)
-- Skill directory structure created: root dir, skill.json, SKILL.md, templates/, references/, assets/
-- kebab-to-title-case conversion: `my-new-skill` → `My New Skill`
-- Error format follows architecture: `Error: <what>` + `  Hint: <how to fix>`
-
-### File List
-
-- `lib/skill-authoring.js` (new)
-- `bin/cli.js` (modified — added import, create-skill case, help text)
-- `test/skill-authoring.test.js` (new)
-
-### Change Log
-
-- 2026-03-19: Implemented Story 3.1 — create-skill scaffolding command with name validation, duplicate detection, file generation, and tests