X Ipe Task Based Code Implementation

Task-Based Skill: Code Implementation

Purpose

Implement code for a single feature by:

1. Querying feature board for full Feature Data Model
2. Learning technical design document thoroughly
3. Reading architecture designs (if referenced in technical design)
4. Generating AAA test scenarios from specification + technical design
5. Routing to language-specific tool skills via semantic matching
6. Validating all Assert clauses pass across tool skill outputs

Important Notes

BLOCKING: Learn x-ipe-workflow-task-execution skill before executing this skill.

Note: If Agent does not have skill capability, go to .github/skills/ folder to learn skills. SKILL.md is the entry point.

BLOCKING: Single Feature Only. This skill operates on exactly ONE feature at a time. Do NOT batch or combine multiple features in a single execution. If multiple features need processing, run this skill separately for each feature.

Workflow Mode: When execution_mode == "workflow-mode", the completion step MUST run the workflow update script via bash: python3 .github/skills/x-ipe-tool-x-ipe-app-interactor/scripts/workflow_update_action.py with workflow_name from workflow.name input, action from workflow.action input, status: "done", and a deliverables keyed dict using ONLY the extract tags defined in workflow-template.json for this action (format: {"tag-name": "path/to/file"}). Do NOT pass a flat list of file paths. Verify the script exits with code 0 before marking the task complete.

Phase 1 Coexistence: AAA scenario generation coexists with x-ipe-tool-test-generation. If AAA generation fails (ambiguous spec, insufficient detail), fall back to x-ipe-tool-test-generation as a safety net. This fallback will be removed in Phase 3 after all tool skills are proven stable.

Implementation Principles

See references/implementation-guidelines.md for detailed principles, coding standards, AAA format specification, and error handling patterns.

IMPORTANT: When process_preference.interaction_mode == "dao-represent-human-to-interact", NEVER stop to ask the human. Instead, call x-ipe-dao-end-user-representative to get the answer. The DAO skill acts as the human representative and will provide the guidance needed to continue.

Input Parameters

input:
  # Task attributes (from task board)
  task_id: "{TASK-XXX}"
  task_based_skill: "x-ipe-task-based-code-implementation"

  # Execution context (passed by x-ipe-workflow-task-execution)
  execution_mode: "free-mode | workflow-mode"  # default: free-mode
  workflow:
    name: "N/A"  # workflow name, default: N/A
    extra_context_reference:  # optional, default: N/A for all refs
      tech-design: "path | N/A | auto-detect"
      specification: "path | N/A | auto-detect"

  # Task type attributes
  category: "feature-stage"
  next_task_based_skill:
    - skill: "x-ipe-task-based-feature-acceptance-test"
      condition: "Verify implementation with acceptance tests"
  process_preference:
    interaction_mode: "{from input process_preference.interaction_mode}"
  feature_phase: "Code Implementation"

  # Required inputs
  feature_id: "{FEATURE-XXX}"

  # Git strategy (from .x-ipe.yaml, passed by workflow)
  git_strategy: "main-branch-only | dev-session-based"
  git_main_branch: "{auto-detected}"

  # Context (from previous task or project)
  specification_link: "x-ipe-docs/requirements/FEATURE-XXX/specification.md"
  mockup_link: "{path | N/A}"       # Derived from specification's Linked Mockups section; N/A if outdated or missing
  technical_design_link: "x-ipe-docs/requirements/FEATURE-XXX/technical-design.md"

  # Tech context (from Technical Design output)
  program_type: "frontend | backend | fullstack | cli | library | skills | mcp | ..."  # non-exhaustive
  tech_stack: []  # e.g. ["Python/Flask", "JavaScript/Vanilla", "HTML/CSS"]

Input Initialization

<input_init>
  <field name="task_id" source="x-ipe-tool-task-board-manager (auto-generated)" />
  <field name="execution_mode" source="x-ipe-workflow-task-execution (from --workflow-mode@{name})" />
  <field name="workflow.name" source="x-ipe-workflow-task-execution (from --workflow-mode@{name})" />
  <field name="process_preference.interaction_mode" source="from caller (x-ipe-workflow-task-execution) or default 'interact-with-human'" />
  <field name="feature_id" source="from previous task (Technical Design) output or task board" />
  <field name="extra_context_reference" source="from workflow context or auto-detect from feature artifacts (x-ipe-docs/requirements/FEATURE-XXX/)" />
  <field name="specification_link" source="IF workflow mode AND extra_context_reference.specification is a path → use it; ELSE → x-ipe-docs/requirements/{feature_id}/specification.md" />
  <field name="technical_design_link" source="IF workflow mode AND extra_context_reference.tech-design is a path → use it; ELSE → x-ipe-docs/requirements/{feature_id}/technical-design.md" />
  <field name="mockup_link">
    <steps>
      1. READ specification at specification_link, find "Linked Mockups" section
      2. IF mockup found AND Linked Date >= latest spec/design update → set mockup_link = "{path}"
      3. ELSE (no mockup, missing section, or Linked Date outdated) → set mockup_link = "N/A"
    </steps>
  </field>
  <field name="git_strategy" source="from .x-ipe.yaml" />
  <field name="git_main_branch" source="auto-detect via `git symbolic-ref refs/remotes/origin/HEAD`" />
  <field name="program_type" source="from Technical Design output" />
  <field name="tech_stack" source="from Technical Design output" />
</input_init>

Definition of Ready

<definition_of_ready>
  <checkpoint required="true">
    <name>Feature exists on feature board</name>
    <verification>Query feature board for feature_id; status must exist</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Feature status is "Designed"</name>
    <verification>Feature board status == "Designed"</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Technical design document exists</name>
    <verification>File exists at x-ipe-docs/requirements/FEATURE-XXX/technical-design.md</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Tracing utility exists in project</name>
    <verification>Check for tracing/ directory or x_ipe.tracing import; if missing, use x-ipe-tool-tracing-creator skill first</verification>
  </checkpoint>
</definition_of_ready>

Execution Flow

BLOCKING: Phase 2 → 3 is BLOCKED until AAA scenarios are generated with coverage validated. BLOCKING: Phase 3: If design needs changes → UPDATE technical design BEFORE implementing. BLOCKING: Step 3.1 special-case delegations run BEFORE semantic routing.

Execution Procedure

<procedure name="code-implementation">
  <!-- CRITICAL: Both DoR/DoD check elements below are MANDATORY -->
  <execute_dor_checks_before_starting/>
  <schedule_dod_checks_with_sub_agent_before_starting/>

  <phase_0 name="Board — Register Task">
    <step_0_1>
      <name>Create Task on Board</name>
      <action>
        Call `x-ipe-tool-task-board-manager` → `task_create.py`:
        - task_type: "Code Implementation"
        - description: summarize work from input context
        - status: "in_progress"
        - role: from input context
        - assignee: from input context
        Store returned task_id for later update.
      </action>
      <output>Task created on board with status in_progress</output>
    </step_0_1>
  </phase_0>

  <phase_1 name="博学之 — Study Broadly">

    <step_1_1>
      <name>Query Feature Board</name>
      <action>
        1. CALL x-ipe-tool-task-board-manager skill with operation=query_feature
        2. RECEIVE Feature Data Model (feature_id, title, version, status, specification_link, technical_design_link)
      </action>
      <constraints>
        - BLOCKING: Feature must exist on board with status "Designed"
      </constraints>
      <output>Feature Data Model with all links and context</output>
    </step_1_1>

    <step_1_2>
      <name>Learn Technical Design</name>
      <action>
        1. Resolve spec/design from Input Initialization (specification_link, technical_design_link)
        2. READ technical_design_link; UNDERSTAND Part 1 (Summary) and Part 2 (Guide)
        3. NOTE architecture references; CHECK Design Change Log for updates
        4. IF mockup_link != "N/A": READ mockup files, extract layout/components/styling for Phase 3
        5. CHECK for skill files (.github/skills/) → FLAG for x-ipe-meta-skill-creator in Phase 3
        6. CHECK for MCP server keywords → FLAG for mcp-builder in Phase 3
      </action>
      <constraints>
        - BLOCKING: Do NOT code until design is understood; STOP and clarify if unclear
        - CRITICAL: If later steps reveal design issues → UPDATE technical-design.md + Design Change Log, then RESUME
      </constraints>
      <output>Implementation requirements understood, mockup references loaded (if applicable)</output>
    </step_1_2>

    <step_1_3>
      <name>Read Architecture Designs</name>
      <action>
        1. CHECK if technical design references architecture patterns
        2. IF no references: skip this step
           ELSE: READ x-ipe-docs/architecture/technical-designs/{component}.md; UNDERSTAND common patterns, interfaces, integration requirements
      </action>
      <output>Architecture patterns understood (or skipped)</output>
    </step_1_3>

  </phase_1>

  <phase_2 name="审问之 — Inquire Thoroughly">

    <step_2_1>
      <name>Generate AAA Scenarios</name>
      <action>
        1. PARSE specification.md: each AC → one @integration scenario (Arrange/Act/Assert)
        2. PARSE technical-design.md Part 2:
           - API endpoints → @backend happy + error scenarios
           - UI components → @frontend happy + error scenarios
           - Validation rules → @backend scenarios; edge cases → matching layer
        3. TAG scenarios: @backend, @frontend, @integration
        4. VALIDATE coverage: every AC ≥1 scenario, every endpoint/component has happy + sad path
        5. Large context (>20 components) → per-layer batches (see references/)
        6. IF generation fails → FALLBACK to x-ipe-tool-test-generation (Phase 1 coexistence)
      </action>
      <constraints>
        - MANDATORY: AAA format: @{tag} / Test Scenario: {name} / Arrange: / Act: / Assert:
        - BLOCKING: Do NOT proceed to Phase 3 until scenarios generated and coverage validated
      </constraints>
      <output>Tagged AAA scenarios with coverage summary</output>
    </step_2_1>

  </phase_2>

  <phase_3 name="慎思之 — Think Carefully">

    <step_3_1>
      <name>Route and Invoke Tool Skills</name>
      <action>
        1. CHECK special-case delegations FIRST:
           a. IF program_type == "skills": DELEGATE to x-ipe-meta-skill-creator; VERIFY DoD; JUMP to step_4_2
              NOTE: Acceptance testing is NOT skipped — x-ipe-task-based-feature-acceptance-test will run structured-review tests on the deliverables
           b. IF MCP server detected: DELEGATE to mcp-builder; VERIFY quality checks; JUMP to step_4_2

        2. DISCOVER: SCAN .github/skills/x-ipe-tool-implementation-*/ for available tool skills

        3. READ CONFIG: Read x-ipe-docs/config/tools.json → extract stages.implement.implementation section
           - IF section missing OR empty (only _order key, no tool entries) → config_active = false
           - ELSE (has tool entries beyond _order and _extra_instruction) → config_active = true

        4. FILTER ENABLED TOOLS:
           IF config_active == false:
             → All discovered tools treated as ENABLED (backwards compatibility)
           ELSE (config_active == true):
             → FOR EACH discovered tool skill:
               a. Look up key "x-ipe-tool-implementation-{name}" in config
               b. IF key exists AND value is true → ENABLED
               c. IF key exists AND value is false → DISABLED, log: "skipped x-ipe-tool-implementation-{name} (disabled)"
               d. IF key does NOT exist (undeclared) → DISABLED (opt-in required), log: "skipped x-ipe-tool-implementation-{name} (undeclared, default disabled)"

        5. FORCE-ENABLE GENERAL: x-ipe-tool-implementation-general is ALWAYS enabled
           - IF general was disabled or undeclared → override to ENABLED
           - Log warning: "x-ipe-tool-implementation-general cannot be disabled — safety net fallback"

        6. LOAD _extra_instruction: IF stages.implement.implementation._extra_instruction exists → use as supplementary semantic routing context

        7. SEMANTIC MATCH: FOR EACH tech_stack entry: semantically match to ENABLED tool skill only
           - No match among enabled skills → assign x-ipe-tool-implementation-general
           - General insufficient → signal "new tool skill needed"
           dao-represent-human → log gap via DAO, continue; else → ask human

        8. INVOKE: FOR EACH matched tool skill (sequentially, backend first):
           a. FILTER AAA scenarios by layer tag
           b. INVOKE with: aaa_scenarios, source_code_path, feature_context, mockup_link (if frontend)
           c. RECEIVE: implementation_files, test_files, test_results, lint_status

        9. IF mockup_link != "N/A" AND frontend components:
           PASS mockup_link in feature_context to frontend tool skill (e.g., x-ipe-tool-implementation-html5)
           Tool skill uses mockup for visual fidelity: layout, components, spacing, color, states

        10. COLLECT all tool skill outputs for validation
      </action>
      <constraints>
        - BLOCKING: Special-case check runs BEFORE semantic routing
        - CRITICAL: Tool skills invoked sequentially, NOT in parallel
        - CRITICAL: Only ENABLED tools participate in semantic matching (step 7)
        - MANDATORY: Use standard tool skill I/O contract (see references/implementation-guidelines.md)
        - MANDATORY: File links in generated markdown MUST use project-root-relative paths so the UI can intercept them and open a preview modal. **Avoid** relative paths (`../`, `./`, `../../`) and absolute filesystem paths (`/Users/...`). **Correct:** `[spec](x-ipe-docs/requirements/EPIC-001/specification.md)`, `[skill](.github/skills/x-ipe-task-based-bug-fix/SKILL.md)`. **Wrong:** `[spec](../specification.md)`, `[spec](./specification.md)`.
        - MANDATORY: Log diagnostic messages for all skipped (disabled/undeclared) tools
      </constraints>
      <output>All tool skill outputs collected</output>
    </step_3_1>

  </phase_3>

  <phase_4 name="明辨之 — Discern Clearly">

    <step_4_1>
      <name>Validate Tool Skill Results</name>
      <action>
        1. FOR EACH tool skill output: verify all Assert clauses (count pass/fail); verify lint_status == "pass"
        2. IF failing Asserts: re-invoke failed tool skill with original scenarios + error context
           - Retry succeeds → continue; retry fails → preserve passing results, escalate
           dao-represent-human → log failure via DAO; else → escalate to human
        3. RUN @integration scenarios: verify cross-layer behavior with mocking
        4. IF integration fails: report contract mismatch
           dao-represent-human → log via DAO; else → report to human
        5. PRODUCE aggregated report: per-skill pass/fail, integration results, overall status
      </action>
      <success_criteria>
        - All @backend, @frontend, @integration Assert clauses pass; all lint checks pass
      </success_criteria>
      <output>Aggregated validation report (PASS/FAIL)</output>
    </step_4_1>

    <step_4_2>
      <name>Apply Tracing Instrumentation</name>
      <action>
        1. IF no tracing infrastructure (no x_ipe.tracing module) or only skill/config files modified: skip
        2. ELSE: INVOKE x-ipe-tool-tracing-instrumentation for all modified files
           - REVIEW decorators (INFO for public, DEBUG for helpers)
           - APPLY with sensitive param redaction; RE-RUN tests to verify
      </action>
      <output>Tracing decorators applied; tests still pass</output>
    </step_4_2>

  </phase_4>

  <phase_5 name="笃行之 — Practice Earnestly">

    <step_5_1>
      <name>Update Workflow Status</name>
      <action>
        1. IF execution_mode == "workflow-mode":
           a. Run `python3 .github/skills/x-ipe-tool-x-ipe-app-interactor/scripts/workflow_update_action.py` with: workflow_name, action, status: "done", feature_id,
              deliverables: {"impl-files": "{path}", "impl-folder": "{path}"}
           b. Log: "Workflow action status updated to done"
        2. Verify all DoD checkpoints
        3. Output task completion summary
      </action>
      <output>Task completion output, workflow_action_updated</output>
    </step_5_1>

    <step_5_2>
      <name>Update Board</name>
      <action>
        1. Call `x-ipe-tool-task-board-manager` → `task_update.py`:
           - task_id: from Phase 0
           - status: "done"
           - output_links: list of deliverables produced in this skill execution
        2. Call `x-ipe-tool-task-board-manager` → `feature_update.py`:
           - feature_id: from input context
           - status: "Implemented"
      </action>
      <output>Task marked done, feature status updated to Implemented</output>
    </step_5_2>

  </phase_5>

  <phase_6 name="继续执行（Continue Execute）">
    <step_6_1>
      <name>Decide Next Action</name>
      <action>
        Collect the full context and task_completion_output from this skill execution.

        IF process_preference.interaction_mode == "dao-represent-human-to-interact":
          → Invoke x-ipe-dao-end-user-representative with:
            type: "routing"
            completed_skill_output: {full task_completion_output YAML from this skill}
            next_task_based_skill: "{from output}"
            context: "Skill completed. Study the context and full output to decide best next action."
          → DAO studies the complete context and decides the best next action
        ELSE (interact-with-human):
          → Present next pipeline step hint to human:
            "✅ Code implementation complete for {feature_id}.
             Next step: Acceptance Testing — run acceptance tests for {feature_id}.
             Want me to proceed?"
          → Wait for human instruction
      </action>
      <constraints>
        - BLOCKING (manual): Human MUST confirm or redirect before proceeding
        - BLOCKING (auto): Proceed after DoD verification; auto-select next task via DAO
      </constraints>
      <output>Next action decided with execution context</output>
    </step_6_1>
    <step_6_2>
      <name>Execute Next Action</name>
      <action>
        Based on the decision from Step 6.1:
        1. Load the target task-based skill's SKILL.md
        2. Generate an execution plan from the skill's Execution Flow table
        3. Start execution from the skill's first phase/step
      </action>
      <constraints>
        - MUST load the skill before executing — do not skip skill loading
        - Execution follows the target skill's procedure, not this skill's
      </constraints>
      <output>Next task execution started</output>
    </step_6_2>
  </phase_6>

</procedure>

See references/implementation-guidelines.md for detailed sub-procedures per step.

Output Result

task_completion_output:
  category: "feature-stage"
  status: completed | blocked
  next_task_based_skill:
    - skill: "x-ipe-task-based-feature-acceptance-test"
      condition: "Verify implementation with acceptance tests"
  process_preference:
    interaction_mode: "{from input process_preference.interaction_mode}"
  execution_mode: "{from input}"
  workflow:
    name: "{from input}"
  workflow_action: "{workflow.action}"   # triggers workflow status update when execution_mode == workflow-mode
  workflow_action_updated: true | false # true if workflow_update_action.py was run
  task_output_links:
    - "src/"
    - "tests/"
  feature_id: "{FEATURE-XXX}"
  feature_title: "{title}"
  feature_version: "{version}"
  feature_phase: "Code Implementation"

Definition of Done

CRITICAL: Use a sub-agent to validate DoD checkpoints independently.

<definition_of_done>
  <checkpoint required="true">
    <name>Context gathered (board queried + design learned)</name>
    <verification>Feature Data Model received with all links; agent can describe implementation plan from design</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>AAA scenarios generated OR special-case delegation invoked</name>
    <verification>Either AAA scenarios exist with coverage validated, or program_type triggered skill-creator/mcp-builder delegation (acceptance testing still required via feature-acceptance-test skill)</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Tool skills invoked and all assertions pass</name>
    <verification>All matched tool skills returned implementation_files, test_files, test_results, lint_status; aggregated validation report shows all pass (or delegation DoD satisfied)</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Implementation matches technical design</name>
    <verification>Compare implemented components against design document</verification>
  </checkpoint>
  <checkpoint required="if-applicable">
    <name>Frontend matches current mockups</name>
    <verification>If feature has current mockups in specification, UI layout/components/styling match the mockup</verification>
  </checkpoint>
  <checkpoint required="if-applicable">
    <name>Special-case delegations used correctly (skill-creator / mcp-builder)</name>
    <verification>If design includes .github/skills/ files, created by x-ipe-meta-skill-creator; if it requires MCP server, built using mcp-builder skill (not directly)</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Code follows YAGNI and KISS principles</name>
    <verification>No functionality beyond design spec; no unnecessary abstractions or over-engineering</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Linter passes and test coverage ≥80% for new code</name>
    <verification>Run ruff check / eslint with zero errors; run pytest --cov=src tests/ and check coverage report</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Tracing decorators and redact annotations applied</name>
    <verification>Public functions have @x_ipe_tracing decorators; password/token/secret/key params have redact=[] set (skip if only skill files)</verification>
  </checkpoint>
  <checkpoint required="if-applicable">
    <name>Workflow Action Updated</name>
    <verification>If execution_mode == "workflow-mode", ran `workflow_update_action.py` script with status "done" and deliverables keyed dict</verification>
  </checkpoint>
</definition_of_done>

MANDATORY: After completing this skill, return to x-ipe-workflow-task-execution to continue the task execution flow.

Patterns & Anti-Patterns

Examples

See references/examples.md for detailed execution examples including:

• Standard backend+frontend feature with AAA orchestration
• Skills-type feature delegated to skill-creator
• AAA generation fallback to test-generation (Phase 1)
• Tool skill retry on failure

Converted and distributed by TomeVault — claim your Tome and manage your conversions.