Add Feature

!../principles/SKILL_BODY.md

!../tool-gitnexus/SKILL_BODY.md

New Feature / Module Workflow

Core Principle

When adding new features, integrate into the existing architecture like a native, not an outsider who starts from scratch. New code should be fully consistent with existing code in style, structure, and interaction patterns.

Complete Execution Workflow

Progress tracking: At the start of each step, output an updated progress block. For Lightweight tasks show only Steps 3–4; for Medium/Large tasks show all steps.

Add Feature Progress
✓ Step 1: Architecture Research     — <one-line finding>
→ Step 2: Solution Design + Confirm — in progress
○ Step 2.5: TDD Contract Tests      — (Large/Medium only)
○ Step 3: Implement
○ Step 4: Architecture Audit

Replace ○ with → for the current step, and ✓ once complete.

Step 1: Understand the Existing Architecture

Before starting, you must be able to answer the following questions:

Architecture awareness:

• What architectural pattern does the project use? (MVC / MVVM / Clean Architecture / Component-based / Microservices…)
• How are similar existing features implemented? (Find the best reference)
• What is the logic behind the project's directory structure? (By layer, by feature, by domain?)

Positioning analysis:

• Which layer does the new feature belong to? Where is its entry point?
• Which existing modules does the new feature need to depend on?
• Are there already extendable abstraction points (e.g., existing strategy interfaces, factory registries, event buses), or do new ones need to be created?

Reference module:

• Find the most similar existing module to the new feature as an implementation reference
• Observe its file structure, naming conventions, dependency injection approach, error handling patterns, and test organization
• The new module should follow the same patterns as closely as possible

🔗 When GitNexus is available, use query / context MCP tools for architecture exploration.

─── Pre-Implementation Research Checklist ───────────
[ ] Understand the project architecture pattern and directory organization
[ ] Found the most similar reference module
[ ] Determined which layer the new feature belongs to
[ ] Determined the new feature's dependencies
[ ] Confirmed whether there are extendable abstraction points
[ ] Confirmed no overlap with responsibilities of existing modules
─────────────────────────────────────────────────────

Step 2: Design the Solution

Before writing code, clarify the design:

Location decision:

• Place it at the same directory level as similar features
• If it's an entirely new domain, create a parallel structure referencing existing module directory structure

Integration approach (priority order, high to low):

─── Integration Strategy Priority ───────────────────
1. Registry-based: Register with existing factory/registry/routing table → zero changes to existing code
2. Extension-point-based: Implement existing abstraction/strategy interface → add only, don't modify
3. Event-driven: Publish/subscribe via event bus → decoupled from existing modules
4. Config-driven: Enable new feature through config files → main flow is unaware
5. Invasive: Modify existing module code to integrate new feature → last resort
─────────────────────────────────────────────────────

For large tasks, inform the user of:

• Which integration approach is being used
• The responsibility boundary of the new module
• How it interacts with existing modules
• Expected file structure

Confirmation Gate (between Step 2 and Step 3)

For Medium and Large tasks, after presenting the design, use the confirmation gate with:

• question: A concise Implementation Plan (see format below)
• options:
  • "Yes, proceed with implementation"
  • "No — let's adjust the design"

Implementation Plan format:

Integration strategy : <which priority level from the Integration Strategy list>
New module location  : <file/directory path>
Public interfaces    : <what is exposed>
Existing code touched: <files modified, or "none — pure addition">
Dependencies         : <what this module depends on>

Decision rules by task scale:

If user selects "No": ask "What would you like to change about the design?", revise the Implementation Plan, and use the confirmation gate again before proceeding.

Step 2.5: TDD Mode — Write Contract Tests First (Medium / Large Tasks Only)

Skip this step for Lightweight tasks. Only activate when the task scale is Medium or Large (per §3.2).

§P config check: read .sextant.yaml before prompting.

• tdd: enforce → skip the prompt; TDD is mandatory for all tasks
• tdd: default_on → treat both Large and Medium as default Y
• tdd: off or absent → use the scale-based defaults below

TDD mode: write contract tests first? Large task → default Y (opt out explicitly if not applicable) Medium task → default n (opt in if you want contract-first coverage)

If Y:

• Write complete, runnable tests for each new public interface: all three of Arrange, Act, and Assert — no TODO placeholders
• The Act calls the not-yet-implemented function or method directly; the test will fail because the implementation is absent or returns wrong output
• Valid red-light failure: NameError / ImportError / assertion on wrong return value
• Invalid "failure": syntax error, placeholder comment, test that cannot run at all — these are not TDD red tests
• Cover: 1 happy path, 1 null/boundary case, 1 error path
• These tests must fail because the contract is not yet fulfilled — that is the correct red state in red-green-refactor
• For full test writing guidance, link sextant:write-tests.

If N (or Lightweight task): Proceed directly to Step 3.

Step 3: Implement — Follow Architecture Conventions

Naming: Fully consistent with the project's existing naming style (camelCase/snake_case, prefix/suffix conventions, abbreviation habits)

Dependency direction: Only upper layers depend on lower layers; reverse dependencies are not allowed. New modules must not introduce reverse dependencies.

Interface protocol: Interaction with existing modules must be consistent — if existing modules communicate through dependency injection, the new module uses dependency injection; if through event bus, use event bus.

Extend, don't modify: Prioritize OCP-compatible integration; avoid changing existing stable modules.

Internal module structure:

• Internal classes/functions are private by default; only expose necessary public interfaces
• Public interfaces must have explicit type declarations and parameter validation
• If the module needs to share data structures with other modules, place them in a dedicated shared layer

Hollywood Principle: New modules only declare dependencies (constructor injection / config registration) and do not proactively pull them.

# ✅ Correct dependency approach for new module
class NewFeatureService:
    def __init__(self, repo: FeatureRepository, bus: EventBus):
        self._repo = repo
        self._bus = bus

# ❌ Incorrect dependency approach for new module
class NewFeatureService:
    def __init__(self):
        self._repo = MySQLFeatureRepository("localhost")  # Self-construct
        self._bus = EventBus.get_instance()                # Proactively pull

Step 4: Architecture Compliance Audit (Required)

After completing the new module, run through an architecture audit:

─── New Module Architecture Audit Checklist ─────────
[ ] Is the layering correct? No layer-crossing calls?
[ ] Has any circular dependency been introduced?
[ ] Has any existing module's boundary been violated? (No direct references to other modules' internal implementations)
[ ] Does the new module's responsibility overlap with existing modules?
[ ] Is the external interface consistent with project style? (Naming, parameter style, error handling)
[ ] Has any new global state or side effects been introduced?
[ ] Is the dependency direction compliant? Any reverse dependencies?
[ ] Does it follow the Hollywood Principle? (Dependencies injected, not pulled)
[ ] Does documentation / comments / type definitions / routing config need to be updated?
[ ] Does it need to be registered with existing factories / registries / config files?
─────────────────────────────────────────────────────

Audit results must be clearly communicated to the user: Passed ✅ or Issues found ⚠️ (with specific details).

Common Pitfalls

Sprint State Integration

If .sextant/state.json exists in the project root and the current task matches a sprint task:

• On start: offer to update the task's status from pending → in_progress. Ask: "Update sprint state to mark Task N as in_progress?"
• On completion (acceptance condition met): offer to update status to done. Ask: "Update sprint state to mark Task N as done?"
• On blocker (test failure, missing dependency, unresolvable ambiguity that halts progress): surface the issue, then ask: "Mark Task N as blocked and record the reason in flags?" If confirmed, set status: "blocked" and append {"task": N, "reason": "<one-sentence blocker description>"} to the top-level flags array. Do not proceed to the next task while a task is blocked.

Do not write the file without explicit user confirmation. If the user declines, continue without state updates.

Reply Format

End every new-feature response with this block (omit a field only if it genuinely has nothing to report):

Feature Summary: