@martinffx/atelier 2.0.0 → 3.0.0

package/skills/spec-plan/SKILL.md

@@ -3,7 +3,7 @@ name: spec-plan
 description: >
   Write approved implementation plans in one of two modes. Explicit Inline mode creates a
   conversational plan for bounded work. Spec-backed Plan converts an approved design.md into
-  plan.json and optional tracked tasks. Trigger after spec-orchestrator selects a mode, when
+  plan.json and optional tracked tasks. Trigger after atelier-orchestrator selects a mode, when
   the user asks to plan work, or after spec-brainstorm completes. Direct invocation without a
   selected mode uses Spec-backed Plan. Do NOT use for research or execution.
 user-invocable: true
@@ -15,7 +15,7 @@ Write a proportional plan so clear that any engineer can follow it. The selected
 mode determines whether the plan stays in the conversation or becomes a persisted structured
 artifact. This skill does not write code.
 
-`spec-orchestrator` owns automatic classification and the human may override it. When this
+`atelier-orchestrator` owns automatic classification and the human may override it. When this
 skill is directly invoked without a selected mode, use Spec-backed Plan. If Inline planning
 reveals substantial design or coordination needs, ask the human whether to switch to a
 Spec-backed Plan before presenting the plan.
@@ -24,30 +24,16 @@ Spec-backed Plan before presenting the plan.
 
 ### Inline Plan (when explicitly selected)
 
-No repository artifact and no task tracker entry. Present the plan in conversation using:
-
-```markdown
-## context
-
-## scope
-
-## changes
-
-## files
-
-## validation
-```
+No repository artifact and no task tracker entry. Read
+`references/plan_template.md` and present the plan in conversation using its
+structure. Omit optional subsections rather than rendering empty headings.
 
 ## Inline Plan Workflow
 
 Read enough of the codebase to identify the current behavior, boundaries, affected files,
-and concrete validation. Keep the plan proportional. Populate every section:
-
-- `context`: Current behavior, relevant constraints, and why the change is needed
-- `scope`: Explicit in-scope and out-of-scope boundaries
-- `changes`: Ordered implementation changes at useful engineering granularity
-- `files`: Exact files expected to be created, modified, or deleted
-- `validation`: Concrete tests, checks, or manual verification
+and concrete validation. Keep the plan proportional to implementation risk. Fill the
+template with confirmed, file-and-symbol-level details, including cross-file wiring or
+ordering constraints where they matter.
 
 Do not manufacture phases, task IDs, dependency graphs, acceptance matrices, `design.md`,
 `plan.json`, Beads issues, or harness todos. The conversation is the plan artifact.
@@ -56,12 +42,18 @@ Do not manufacture phases, task IDs, dependency graphs, acceptance matrices, `de
 
 **STOP. Wait for human review.**
 
-If the human requests changes, revise the plan in conversation and present the complete
-plan again. Do not implement until the human explicitly approves it. A material scope
-change after approval also requires a revised plan and renewed approval.
+If the human requests any adjustment, apply it to the working plan and re-present the
+entire updated plan using `references/plan_template.md`. Include unchanged sections so
+the human reviews one coherent plan. Never respond with only the changed text, an
+affected section, a summary, or an acknowledgement. A one-word correction is still a
+plan revision: incorporate it and present the complete plan again.
+
+Every revision invalidates prior approval. End each revised plan with "Inline Plan ready
+for review." and stop until the human explicitly approves that complete version. Do not
+implement until the current plan is approved.
 
 Approval authorizes implementation. Implement the approved conversational plan directly using
-the Inline execution safeguards in `spec-orchestrator`. Do not invoke `spec-implement`,
+the Inline execution safeguards in `atelier-orchestrator`. Do not invoke `spec-implement`,
 `spec-finish`, `code-subagents`, or task tracking.
 
 Do not create planning artifacts or tracker entries during this handoff.
@@ -286,7 +278,7 @@ Tell the human:
 Do not start implementing. That's spec-implement's job.
 
 If implementation reveals missing tasks, update plan.json. If design is wrong,
-loop back to research. See **spec-orchestrator** for iteration patterns.
+loop back to research. See **atelier-orchestrator** for iteration patterns.
 
 ---
 
@@ -294,8 +286,8 @@ loop back to research. See **spec-orchestrator** for iteration patterns.
 
 | Selected mode / human says | You do |
 |----------------------------|--------|
-| Inline / "write a plan" | Present the five-section Inline Plan, stop |
-| Inline / "I added notes" | Revise and re-present the complete Inline Plan |
+| Inline / "write a plan" | Present the complete Inline Plan from the template, stop |
+| Inline / "I added notes" | Apply the changes, re-present the entire updated Inline Plan, and stop for renewed approval |
 | Inline / "approved" | Implement the approved conversational plan directly; create no artifacts |
 | Spec-backed / "write a plan" | Write the plan draft from design.md, stop |
 | Spec-backed / "I added notes" | Re-read, address all notes, do NOT implement |

package/skills/spec-plan/references/plan_template.md

@@ -0,0 +1,77 @@
+## Context
+
+Describe why the change is needed and summarize the relevant current behavior.
+Include repository facts, constraints, dependencies, and prior work that the
+implementation must preserve. Contrast the current and desired states when useful.
+
+Write enough for an engineer unfamiliar with the immediate problem to understand
+the plan. Do not repeat implementation steps that belong under Changes.
+
+### Decisions
+
+Include this subsection when the plan depends on meaningful implementation choices.
+
+Record the chosen architecture, interfaces, ownership boundaries, data flow,
+execution order, or technology choices. Explain why the selected approach fits
+the existing codebase. Mention rejected alternatives only when doing so prevents
+the implementer from revisiting a settled choice.
+
+Omit this subsection when the implementation is mechanical or the repository
+already dictates the approach.
+
+### Scope
+
+Include this subsection when the boundaries of the work are not obvious or when
+closely related work must be explicitly excluded.
+
+State what is in scope and out of scope. Identify behavior that must remain
+unchanged and any adjacent systems, cleanup, or follow-up work that this plan
+does not address.
+
+Omit this subsection when the Context and Changes already make the boundaries
+unambiguous.
+
+## Changes
+
+Describe the implementation in dependency order. Use a numbered list when there
+is more than one change.
+
+For each change:
+
+- Start with the exact file path and a concise description.
+- Name the affected functions, types, routes, configuration keys, or other symbols.
+- Explain the current behavior when it matters to the change.
+- Describe the required behavior and important implementation constraints.
+- Explain cross-file wiring, data flow, error handling, and execution order where relevant.
+- Identify files to create, modify, rename, or delete.
+- Mention corresponding test changes alongside the behavior they verify.
+- Use a short signature or pseudocode only when it removes material ambiguity.
+
+The plan should provide enough detail for another engineer to implement without
+rediscovering the approach, while avoiding line-by-line coding instructions.
+
+## Known Limitations
+
+Include this section only when the planned implementation intentionally leaves
+limitations, risks, unsupported cases, deferred cleanup, or follow-up work.
+
+Explain the practical impact of each limitation. Do not use this section for
+unresolved decisions that must be settled before implementation.
+
+Omit the entire section when there are no known limitations.
+
+## Verification
+
+List the concrete checks required after implementation.
+
+For each check:
+
+- Provide the exact command or manual action when known.
+- State the expected outcome or invariant being verified.
+- Include focused tests for changed behavior.
+- Include broader build, test, lint, or type-check commands appropriate to the repository.
+- Include repository searches or state checks when confirming removals, migrations,
+  conflict resolution, generated files, or absence of stale references.
+- Note any verification that cannot be performed locally and why.
+
+Prefer the smallest focused check first, followed by broader regression checks.

package/skills/python-architecture/SKILL.md

@@ -1,148 +0,0 @@
----
-name: python-architecture
-description: Python application architecture with functional core, effectful shell, DDD, and data modeling. Use when designing application layers, separating pure business logic from IO, defining domain models, implementing validation, or structuring bounded contexts.
-user-invocable: false
----
-
-# Python Application Architecture
-
-Modern Python application architecture following functional core / imperative shell pattern, Domain-Driven Design, and type-safe data modeling.
-
-## Core Principle: Functional Core / Imperative Shell
-
-Separate pure business logic from side effects:
-
-- **Functional Core**: Pure functions, business logic, no IO
-- **Imperative Shell**: Coordinates external dependencies, handles side effects
-
-See [references/functional-core.md](references/functional-core.md) for detailed patterns and examples.
-
-## Layered Architecture
-
-Follow bottom-up dependency flow:
-
-```
-Router/Handler → Service → Repository → Entity → Database
-```
-
-Each layer depends only on layers below.
-
-**Responsibilities:**
-- **Entity**: Domain models, validation, business rules, data transformations (fromRequest, toRecord, toResponse)
-- **Repository**: Abstract storage interface, returns domain entities
-- **Service**: Business workflows, orchestrates entities and repositories
-- **Router/Handler**: HTTP handling, delegates to services
-
-## Domain Models
-
-### Entity Example
-
-```python
-from dataclasses import dataclass
-from uuid import UUID
-from decimal import Decimal
-
-@dataclass
-class Order:
-    """Entity - has identity and encapsulated behavior"""
-    id: UUID
-    customer_id: UUID
-    total: Decimal
-    status: str
-
-    def apply_discount(self, rate: Decimal) -> None:
-        """Business rule - encapsulated in entity"""
-        if self.status == "pending":
-            self.total = self.total * (1 - rate)
-
-    @classmethod
-    def from_request(cls, req, customer_id: UUID) -> "Order":
-        """Transform API request → entity"""
-        return cls(id=uuid4(), customer_id=customer_id, total=Decimal("0"), status="pending")
-
-    def to_response(self):
-        """Transform entity → API response"""
-        return {"id": self.id, "total": self.total, "status": self.status}
-```
-
-### Value Object Example
-
-```python
-from dataclasses import dataclass
-
-@dataclass(frozen=True)
-class Money:
-    """Value object - immutable, no identity"""
-    amount: Decimal
-    currency: str
-
-    def add(self, other: "Money") -> "Money":
-        if self.currency != other.currency:
-            raise ValueError("Cannot add different currencies")
-        return Money(self.amount + other.amount, self.currency)
-```
-
-See [references/ddd.md](references/ddd.md) for aggregates, bounded contexts, and domain services.
-
-## Repository Pattern
-
-Abstract storage behind interface:
-
-```python
-from abc import ABC, abstractmethod
-from typing import Optional
-
-class OrderRepository(ABC):
-    """Abstract repository - interface only"""
-
-    @abstractmethod
-    def get(self, order_id: UUID) -> Optional[Order]:
-        pass
-
-    @abstractmethod
-    def save(self, order: Order) -> None:
-        pass
-
-class PostgresOrderRepository(OrderRepository):
-    """Concrete implementation"""
-
-    def get(self, order_id: UUID) -> Optional[Order]:
-        record = self.session.get(OrderRecord, order_id)
-        return Order.from_record(record) if record else None
-
-    def save(self, order: Order) -> None:
-        record = order.to_record()
-        self.session.merge(record)
-        self.session.commit()
-```
-
-## Data Modeling
-
-- **dataclasses**: Domain models and internal logic (lightweight, standard library)
-- **Pydantic**: API boundaries (validation, JSON schema, OpenAPI)
-- **Entity transformations**: `from_request()`, `to_response()`, `from_record()`, `to_record()`
-
-See [references/data-modeling.md](references/data-modeling.md) for validation patterns, Pydantic features, and transformation examples.
-
-## Best Practices
-
-1. **Pure functions first** - Write business logic without IO dependencies
-2. **Entity encapsulation** - Keep business rules inside entities
-3. **Repository abstraction** - Hide storage details, work with domain entities
-4. **Validate at boundaries** - Use Pydantic at API edges, simple validation in entities
-5. **Immutable value objects** - Always use `frozen=True`
-6. **Single Responsibility** - Each layer has one reason to change
-7. **Dependency direction** - Always depend on abstractions, not implementations
-
-## Anti-Patterns
-
-❌ **Anemic Domain Model** - Entities with only getters/setters, all logic in services
-❌ **Transaction Script** - All logic in service layer, entities just data
-❌ **Leaky Abstraction** - Repository exposing database details
-❌ **God Object** - Entity with too many responsibilities
-❌ **Mixed Concerns** - Business logic calling IO directly
-
-For detailed examples, patterns, and decision trees, see the reference materials:
-- [references/functional-core.md](references/functional-core.md) - Core vs shell separation
-- [references/ddd.md](references/ddd.md) - DDD patterns, aggregates, bounded contexts
-- [references/data-modeling.md](references/data-modeling.md) - dataclasses, Pydantic, transformations