Implementation Task Workflow

This page describes the standard workflow for executing an implementation task at Arda. The workflow applies whenever a task is specified in a directory containing a specification.md file.

Task Setup

Each task lives in a task directory that contains a specification.md file defining the goal, acceptance criteria, sub-tasks, and any other requirements. This directory is the root for the task. Create byproducts/ and session/ subdirectories within it as the task progresses.

Phase 1: Analysis and Planning (Mandatory)

Before writing any code:

1. Read the specification.md fully. Identify ambiguities or missing requirements and resolve them with the relevant stakeholder. Update specification.md with any clarifications or additions.
2. Review the technical documentation for relevant existing documentation. Add references to the task specification if they are not already present.
3. Produce a written Implementation Plan that lists the steps to be taken and calls out any remaining questions.
4. Obtain explicit approval before modifying any pre-existing files. You do not need permission to create new files, new subdirectories, or to modify files that were themselves created during this task.

Phase 2: Implementation

Execute the approved plan. For each sub-task defined in specification.md, apply the relevant verification step before moving to the next sub-task:

• Kotlin back-end changes: run the back-end unit tests as described in dev-workflows.md.
• Documentation changes: build the technical documentation site and verify it renders without errors.

At the end of the overall task, perform the full end-to-end verification sequence:

1. Lint the documentation.
2. Deploy to the local k8s environment.
3. Run the CI/CD api-test suite locally.

See dev-workflows.md for the exact commands for each of these steps.

Multi-Repository Changes

When a task spans multiple repositories:

• Follow the release-lifecycle conventions (available in the workspace) for CHANGELOG updates, PR merge ordering, version catalog updates, and composite build safety.
• Include these as explicit sub-tasks in the implementation plan before starting work.

Phase 3: Byproduct Generation

After implementation is complete, create a byproducts/ subdirectory inside the task directory and produce the following documents. Each document must follow the project’s document-writing conventions (front matter, footer, path references, diagram format, and style guidelines).

File	Contents
changelog.md	Summary of the changes made.
learnings.md	New knowledge about the codebase or technologies useful for future tasks.
suggestions.md	Improvement suggestions, identified risks, technical debt, documentation gaps, and task specification improvements.
alternatives.md	Key alternatives considered but not implemented, with rationale for the choices made.
skipped.md	Sub-tasks, requirements, or acceptance criteria not fully implemented, with reasons.
specification-post.md	Re-worked version of the original specification reflecting the final implementation.

Byproduct templates are available in the workspace knowledge base.

Phase 4: Session Logging

Create a session/ subdirectory inside the task directory. Copy all plans, walkthroughs, and relevant intermediate artifacts to this directory before concluding the task. This preserves the decision trail for future reference and for onboarding anyone who picks up the work later.

Phase 5: Knowledge Publication

If a learnings.md file was produced in Phase 3, incorporate the key insights into the shared knowledge base so they benefit future tasks across the team.

---

Copyright: (c) Arda Systems 2025-2026, All rights reserved