Shipkit Engineering Definition

Prerequisites

Required (fail gracefully if missing):

• .shipkit/product-definition.json — features, UX patterns, differentiators

Recommended (enrich the proposal):

• .shipkit/why.json — project purpose and vision
• .shipkit/goals/strategic.json — project stage and constraints
• .shipkit/stack.json — existing technology constraints
• .shipkit/product-discovery.json — pain points for traceability

Optional (for existing projects):

• .shipkit/codebase-index.json — existing code structure

If product-definition.json is missing, tell the user: "Run /shipkit-product-definition first — I need to know what features to design mechanisms for." and stop.

Process

Completion Tracking

After reading prerequisites, create tasks:

• TaskCreate: "Design 2-5 mechanisms mapped to features"
• TaskCreate: "Define 2-6 components mapped to mechanisms"
• TaskCreate: "Capture cross-cutting design decisions"
• TaskCreate: "Write engineering-definition.json"
• TaskCreate: "Derive and write architecture.json"

engineering-definition.json alone is NOT done — architecture.json must also be derived and written. This applies to propose mode (Step 0c) as well.

Step 0: Check for Existing File

Fork context — no user prompts. You are dispatched in a fork and have no user channel. Skip the file-exists menu entirely.

1. Check if .shipkit/engineering-definition.json exists
2. If exists: read .shipkit/reviews/direction-assessment.json if present. If the latest review lists a gap against this artifact, archive the existing file to .shipkit/.archive/engineering-definition.YYYY-MM-DD.json and regenerate addressing the gap. Otherwise, read the existing file and exit early with a "no changes needed" report — the reviewer already accepted it.
3. If no file exists: proceed to Step 0c (propose mode).

Step 0c: Propose Mode (Context-Driven)

If .shipkit/product-definition.json exists, attempt to propose a technical approach without asking:

1. Read .shipkit/product-definition.json (features, UX patterns, differentiators)
2. Read .shipkit/why.json if exists (vision, constraints) 2b. Read .shipkit/goals/strategic.json if exists (stage)
3. Read .shipkit/stack.json if exists (technology capabilities)
4. Read .shipkit/product-discovery.json if exists (pain points)
5. For each feature, propose the technical mechanism to implement it
6. Present the proposal as a Feature → Mechanism → Components flow:

Based on the product definition, here's a proposed technical approach:

Feature: [feature from product-definition]
  → Mechanism: [how we build it technically]
    → Components: [modules/services involved]

Feature: [another feature]
  → Mechanism: [technical approach]
    → Components: [modules/services]

Key Design Decisions: [cross-cutting technical choices]

7. Write engineering-definition.json directly and present a summary
8. The orchestrator's review cycle will catch issues — no confirmation needed

Step 1: Gather Context

Read these files:

.shipkit/product-definition.json  → features, UX patterns, differentiators (REQUIRED)
.shipkit/why.json                 → vision, stage, constraints (RECOMMENDED)
.shipkit/stack.json               → tech capabilities (RECOMMENDED)
.shipkit/product-discovery.json   → pain points for traceability (RECOMMENDED)
.shipkit/codebase-index.json      → existing code (OPTIONAL)

Extract from product-definition.json:

• All features (F-001, F-002, etc.) — the WHAT that needs mechanisms
• UX patterns (P-001, P-002, etc.) — interaction patterns that constrain implementation
• Feature dependencies — influences mechanism ordering
• Differentiators — technical requirements implied by competitive claims

Step 2: Design Core Mechanisms

For each feature (or group of related features), define a mechanism:

Fork context — no user prompts. Infer mechanisms from upstream context (.shipkit/ files). If insufficient, return gaps_found and exit; the reviewer will trigger re-dispatch.

For each mechanism, capture:

• Name — concise mechanism name
• Description — how it works at a technical level
• Implements features — which feature IDs from product-definition
• Key design choices — decisions made with rationale and alternatives

Aim for 2-5 mechanisms. Each feature should be served by at least one mechanism. Mechanisms can serve multiple features.

Step 3: Define Component Structure

Based on mechanisms, define how the solution is modularized:

Fork context — no user prompts. Infer component structure from mechanisms and upstream context. If insufficient, return gaps_found and exit; the reviewer will trigger re-dispatch.

For each component, capture:

• Name — component/module/service name
• Responsibility — what it owns (single responsibility)
• Mechanisms — which mechanism IDs it implements
• Interfaces — how it communicates with other components
• Data contracts — key data shapes flowing in/out (types, schemas, API payloads)

Aim for 2-6 components. Each mechanism should map to at least one component.

Data contracts note: Define the key data shapes at component boundaries — request/response types, shared models, event payloads. Use Zod schemas, TypeScript types, or JSON Schema depending on the stack.

Step 4: Capture Design Decisions

Identify cross-cutting technical decisions that affect multiple mechanisms or components:

• Technology choices (framework, database, hosting)
• Architectural patterns (monolith vs microservices, REST vs GraphQL)
• Data flow decisions (SSR vs CSR, caching strategy)
• Security patterns (auth approach, data encryption)

For each decision, capture:

• Decision — what was decided
• Rationale — why this direction
• Alternatives — what was considered but rejected

Step 5: Stack Direction (Greenfield Only)

Skip if .shipkit/stack.json already exists.

For greenfield projects, ask about technology direction:

Fork context — no user prompts. Infer stack direction from existing .shipkit/ context files and mechanism requirements. If insufficient, return gaps_found and exit; the reviewer will trigger re-dispatch.

Capture:

• Recommended technologies (frontend, backend, database, hosting)
• Rationale tied to the mechanism design
• Constraints that drove the choice

Step 6: Present Blueprint and Confirm

Present the full engineering blueprint:

View 1: Technical Design

## Engineering Blueprint: [Product Name]

### Core Mechanisms
1. M-001: [Name] — [description]
   Implements: F-001, F-002
   Design choices: [key decisions]
2. M-002: [Name] — [description]

### Component Structure
1. C-001: [Name] — [responsibility]
   Implements mechanisms: M-001
   Interfaces: [how it connects]

### Design Decisions
1. [Decision] — [rationale]

View 2: Feature → Mechanism Map

### Feature Coverage

  F-001: [Feature Name] → M-001: [Mechanism] via C-001: [Component]
  F-002: [Feature Name] → M-001, M-002 via C-001, C-002
  F-003: [Feature Name] → M-003 via C-003

Fork context — do not prompt for confirmation. Write the blueprint directly. The direction reviewer will flag any misalignment on the next review cycle.

Step 7: Write Engineering Definition + Architecture Decisions

After confirmation, write two files:

1. .shipkit/engineering-definition.json — Full engineering blueprint (mechanisms, components, design decisions, stack direction)

2. .shipkit/architecture.json — Architecture decisions log, derived from the engineering definition. This is the append-only decisions record that downstream skills (plan, spec, preflight, review-shipping) read for pattern context.

{
  "$schema": "shipkit-artifact",
  "type": "architecture-decisions",
  "version": "1.0",
  "lastUpdated": "ISO timestamp",
  "source": "shipkit-engineering-definition",
  "decisions": [
    {
      "id": "ADR-001",
      "decision": "Decision from designDecisions or mechanism designChoices",
      "rationale": "Why",
      "alternatives": ["What was considered"],
      "scope": "cross-cutting | mechanism:M-001",
      "date": "ISO date"
    }
  ],
  "patterns": ["Key architectural patterns in use (e.g., MVC, event-driven, serverless)"],
  "constraints": ["Technical constraints driving decisions"]
}

Derivation: Merge top-level designDecisions (scope: "cross-cutting") with per-mechanism designChoices (scope: "mechanism:M-001") into a flat decisions list. Add any patterns and constraints inferred from the stack and mechanisms.

On update: When engineering-definition.json is updated, regenerate architecture.json. New decisions are appended; existing decisions are preserved with their original dates. This maintains the append-only log property.

See Engineering Definition JSON Schema below.

Step 8: Suggest Next Steps

Engineering blueprint written to .shipkit/engineering-definition.json
Mechanisms: {N} | Components: {N} | Design Decisions: {N}

Next:
  1. /shipkit-product-goals — Define product success criteria; then /shipkit-engineering-goals for engineering criteria
  2. /shipkit-spec — Create specs for features (with mechanism context)

Ready to define success criteria?

Engineering Definition JSON Schema (Quick Reference)

{
  "$schema": "shipkit-artifact",
  "type": "engineering-definition",
  "version": "1.0",
  "lastUpdated": "ISO timestamp",
  "source": "shipkit-engineering-definition",
  "product": {
    "name": "Product name (from product-definition)",
    "stage": "poc|mvp|production|scale"
  },
  "mechanisms": [
    {
      "id": "M-001",
      "name": "Mechanism name",
      "description": "How this works technically",
      "implementsFeatures": ["F-001", "F-002"],
      "designChoices": [
        { "decision": "Choice", "rationale": "Why", "alternatives": ["Rejected option"] }
      ]
    }
  ],
  "components": [
    {
      "id": "C-001",
      "name": "Component name",
      "responsibility": "What it owns",
      "mechanisms": ["M-001"],
      "interfaces": ["REST API to C-002", "Event bus to C-003"],
      "dataContracts": ["Key data shapes at this component's boundaries"]
    }
  ],
  "designDecisions": [
    {
      "decision": "Key choice",
      "rationale": "Why",
      "alternatives": ["What was considered"]
    }
  ],
  "stackDirection": {
    "recommended": { "frontend": "...", "backend": "...", "database": "...", "hosting": "..." },
    "rationale": "Why these choices",
    "constraints": ["Driving factors"],
    "note": "Only for greenfield. Skipped if stack.json exists."
  },
  "summary": {
    "totalMechanisms": 0,
    "totalComponents": 0,
    "totalDesignDecisions": 0
  }
}

Full schema reference: See references/output-schema.md Realistic example: See references/example.json

Graph Relationships

The ID-based cross-references enable these graph traversals:

• Mechanism -> Features: mechanisms[].implementsFeatures references features[].id from product-definition.json
• Component -> Mechanisms: components[].mechanisms references mechanisms[].id
• Feature -> Mechanism (reverse lookup): For any feature in product-definition, find mechanisms where implementsFeatures contains that feature ID

When $ARGUMENTS is Provided

If $ARGUMENTS contains text:

• Focus area: Use to narrow mechanism design to specific features
• --refresh: Start fresh even if engineering-definition.json exists

When This Skill Integrates with Others

Before This Skill

After This Skill

Context Files This Skill Reads

Context Files This Skill Writes

Artifact strategy: replace — Overwrites the existing artifact file. Previous content is not preserved.

Write Strategy: OVERWRITE

Archive location (if replacing):

• .shipkit/archive/engineering-definition/engineering-definition.[timestamp].json

After Completion

Guardrails Check: Before moving to next task, verify:

1. Persistence - Has important context been saved to .shipkit/?
2. Prerequisites - Does the next action need goals or a spec first?
3. Session length - Long session? Consider /shipkit-work-memory for continuity.

Natural capabilities (no skill needed): Implementation, debugging, testing, refactoring, code documentation.

Suggest skill when: User needs to define success criteria (/shipkit-product-goals, /shipkit-engineering-goals), create detailed specs (/shipkit-spec), or update architecture decisions (/shipkit-engineering-definition).

Success Criteria

Engineering blueprint is complete when:

• Product-definition.json read and features extracted
• 2-5 mechanisms defined, each implementing at least one feature
• Every feature served by at least one mechanism
• 2-6 components defined with clear responsibilities
• Key design decisions captured with rationale
• Stack direction captured (greenfield only)
• All cross-references use stable IDs (M-001, C-001)
• Summary counts match actual array lengths
• File saved to .shipkit/engineering-definition.json
• Architecture decisions derived and saved to .shipkit/architecture.json

Remember: This skill captures the technical approach — HOW you build the features defined in product-definition.json. It's the bridge between product design (what users see) and implementation (architecture, specs, code). Each mechanism maps to product features, giving full traceability from user needs through to technical approach.