bigeasyfreeman/skills/architecture-pattern

Skill: Architecture Pattern Scaffolding

Generates port interfaces, implementation guides, directory structures, and other non-placeholder scaffolding from Build Brief architecture pattern decisions. Ensures autonomous coding agents start with the right structure, not a blank file.

---

Trigger

Activated when coding starts (after brief approval and ticket creation). Consumes Section 2 (Architecture Patterns) and Section 8 (Task Breakdown) from the brief.

Input Contract

{
  "build_brief_id": "string",
  "architecture_patterns": [
    {
      "area": "string (e.g., data_access, error_handling, config)",
      "convention": "string (e.g., ports-and-adapters, repository pattern, typed errors)",
      "reference_files": ["string (file paths in repo)"],
      "decision_type": "Type 1 | Type 2"
    }
  ],
  "tasks": [
    {
      "task_id": "string",
      "description": "string",
      "area": "backend | frontend | infra | observability",
      "pattern_ref": "string (which pattern applies)"
    }
  ],
  "repo_path": "string",
  "language": "typescript | python | scala | go | javascript",
  "output_directory": "string"
}

Output Contract

{
  "scaffolded_files": [
    {
      "path": "string",
      "type": "port | adapter | factory | config | test_helper",
      "content": "string",
      "pattern": "string (which architecture pattern)",
      "todos": ["string (what the coding agent needs to implement)"]
    }
  ],
  "directory_structure": "string (tree output)",
  "implementation_guide": "string (instructions for coding agents)",
  "summary": "string"
}

Behavior

1. Analyze Reference Implementations

Before generating anything, read the reference files from the brief:

# Read each reference file to understand the exact convention
cat [reference_file_path]

# Find all files following the same pattern
find . -path "*/domain/repos/*" -o -path "*/ports/*" | head -20
find . -path "*/adapters/*" -o -path "*/server/adapters/*" | head -20

# Find dependency injection / wiring
grep -r "bind\|provide\|register\|inject" --include="*.ts" --include="*.scala" --include="*.py" | head -10

# Find module boundaries
find . -name "index.ts" -o -name "__init__.py" -o -name "mod.rs" | head -20

2. Generate Port Interfaces

For each domain concept identified in the task breakdown, generate a port interface that follows the repo's existing convention.

Detection logic:

• If repo uses traits (Scala): generate trait
• If repo uses abstract classes (Python): generate ABC
• If repo uses interfaces (TypeScript): generate interface
• If repo uses base classes (JavaScript): generate class with throw new Error("Not implemented")
• If repo uses Go interfaces: generate interface

Example outputs by language:

// domain/repos/WidgetRepo.scala
trait WidgetRepo[F[_]]:
  def create(widget: Widget): F[WidgetId]
  def getById(id: WidgetId): F[Option[Widget]]
  def updateStatus(id: WidgetId, status: WidgetStatus): F[Unit]

// domain/repos/WidgetRepo.ts
export interface WidgetRepo {
  create(widget: Widget): Promise<WidgetId>;
  getById(id: WidgetId): Promise<Widget | null>;
  updateStatus(id: WidgetId, status: WidgetStatus): Promise<void>;
}

# domain/repos/widget_repo.py
from abc import ABC, abstractmethod

class WidgetRepo(ABC):
    @abstractmethod
    async def create(self, widget: Widget) -> WidgetId:
        pass

    @abstractmethod
    async def get_by_id(self, id: WidgetId) -> Optional[Widget]:
        pass

    @abstractmethod
    async def update_status(self, id: WidgetId, status: WidgetStatus) -> None:
        pass

3. Generate Adapter Contracts and Implementation Targets

For each port interface, generate only what is safe to scaffold without leaving mergeable placeholders:

• the adapter file path and naming convention in the implementation guide
• constructor and dependency requirements
• pattern rules the real adapter must follow
• failing tests that define the required behavior

Do not generate runtime adapter implementations with placeholder bodies such as NotImplementedError, todo!(), unimplemented!(), pass, or TODO comments in production source paths.

CRITICAL: Scaffolding output is planning context only. It must never satisfy task completion, Definition of Done, or merge gates.

The paired QA test file is the real spec:

# tests/test_postgres_widget_repo.py (generated by QA skill, already failing)
async def test_create_widget_persists():
    """Given valid widget data, When create() called, Then widget exists in DB."""
    repo = PostgresWidgetRepo(test_db)
    widget_id = await repo.create(Widget(name="test"))
    assert await repo.get_by_id(widget_id) is not None

The coding agent receives the contract + the failing test. Its job: create the real implementation directly. Scaffolding is not considered working code.

4. Generate Domain Types

If the task breakdown references new domain types (entities, value objects, enums):

• Generate type definitions following existing conventions
• Place them in the correct directory
• Include validation logic only if the rules are fully specified; otherwise put the requirement in the implementation guide instead of emitting placeholder runtime logic

5. Generate Wiring / Registration

If the repo uses dependency injection or module registration:

• Generate the binding/registration for new ports → adapters
• Follow the existing wiring pattern (e.g., Module, Container, provider, etc.)

6. Generate Directory Structure

Create any new directories needed, following existing conventions:

# Example output
src/
├── domain/
│   ├── entities/
│   │   └── Widget.ts          # NEW: domain entity
│   ├── repos/
│   │   └── WidgetRepo.ts      # NEW: port interface
│   └── errors/
│       └── WidgetErrors.ts    # NEW: typed domain errors
├── server/
│   └── adapters/
│       └── PostgresWidgetRepo.ts  # NEW: adapter implementation target
└── tests/
    └── helpers/
        └── WidgetFactory.ts   # NEW: test factory

7. Generate Implementation Guide

Produce a markdown guide that coding agents consume:

## Implementation Guide for [Feature Name]

### Files to Implement (in order)
1. `domain/entities/Widget.ts` — Define the Widget entity with validation
2. `domain/repos/WidgetRepo.ts` — Port interface scaffold; verify method shape
3. `server/adapters/PostgresWidgetRepo.ts` — Implement the adapter fully from the generated tests and pattern rules; no placeholder methods allowed
4. `server/routes/WidgetRouter.ts` — Add endpoints per task [JIRA-124]
5. `tests/widget.test.ts` — Run QA-generated tests after implementation

### Pattern Rules
- Domain layer MUST NOT import from server layer
- Adapters MUST implement the full port interface
- All errors MUST use typed errors from domain/errors/
- All new dependencies MUST be injected, not imported directly

### Reference Implementations
- Similar port: [file path]
- Similar adapter: [file path]
- Similar router: [file path]

MCP Server Contract

Tool: scaffold_from_patterns

{
  "name": "scaffold_from_patterns",
  "description": "Generate port interfaces, transitional adapter scaffolding, and directory structure from Build Brief architecture patterns",
  "inputSchema": {
    "type": "object",
    "properties": {
      "build_brief": {
        "type": "string",
        "description": "Section 2 (Architecture Patterns) + Section 8 (Task Breakdown) as markdown"
      },
      "repo_path": {
        "type": "string",
        "description": "Path to the repository root"
      },
      "output_directory": {
        "type": "string",
        "description": "Where to write scaffolded files (default: repo source root)"
      },
      "dry_run": {
        "type": "boolean",
        "default": true,
        "description": "If true, show files without creating"
      }
    },
    "required": ["build_brief", "repo_path"]
  }
}

Tool: validate_scaffold

{
  "name": "validate_scaffold",
  "description": "Validate that scaffolded code compiles and follows pattern conventions",
  "inputSchema": {
    "type": "object",
    "properties": {
      "scaffolded_files": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Paths to scaffolded files to validate"
      },
      "repo_path": {
        "type": "string"
      }
    },
    "required": ["scaffolded_files", "repo_path"]
  }
}

CLI Interface

# Preview scaffolding from build brief
adlc-scaffold generate --brief ./build-brief.md --repo ./my-repo --dry-run

# Generate scaffolding
adlc-scaffold generate --brief ./build-brief.md --repo ./my-repo

# Validate scaffolded files compile
adlc-scaffold validate --repo ./my-repo

# Generate implementation guide only
adlc-scaffold guide --brief ./build-brief.md --repo ./my-repo --output ./implementation-guide.md

Quality Gates

• [ ] Every port interface matches the repo's existing convention (trait, interface, ABC, etc.)
• [ ] Every adapter extends/implements its port correctly
• [ ] Scaffolded files compile (type check passes)
• [ ] Directory structure follows existing conventions
• [ ] Domain layer has no imports from infrastructure layer
• [ ] Wiring/registration is generated if DI is used
• [ ] Implementation guide references correct file paths
• [ ] No generated scaffold is treated as complete work
• [ ] Validation fails if scaffold artifacts remain at task completion

Framework Hardening Addendum

• Contract versioning: Scaffolding input/output contracts must include contract_version.
• Schema validation: Validate architecture pattern inputs against canonical Build Brief contract fields before generating scaffolding.
• Idempotency: File generation operations must be idempotent by target path and component identifier to prevent duplicate scaffolding.
• Structured errors: Emit typed failure payloads for pattern mismatch, missing references, or unresolved dependencies.