Ways Of Working

Ways of Working

Development Workflow

Development is agent-first — every change starts as a structured issue and flows through issue → plan → implement → test → review:

1. Create an issue using the devantler-tech/.github issue templates:
   • Feature — user story with acceptance criteria.
   • Bug — expected vs actual behavior with reproduction steps.
   • Chore — user story with acceptance criteria for general tasks.
   • Kata — Improvement Kata for continuous improvement (problem → definition of awesome → target condition → actions).
2. Plan — create a structured implementation plan from the issue before writing code.
3. Implement — execute the plan following the practices in this skill (TDD, quality gates, GitHub Flow, CI/CD).
4. Manual test — validate behavior hands-on before merging. Focus on UX: output must be well-presented and every piece of feedback (errors, warnings, prompts) must be actionable.
5. Code review (optional) — CI's strict linting, scanning, and quality gates are the primary feedback loop, so manual review is not always required.

Testing

Follow the test-driven-development skill rigorously — write the test first, watch it fail, write minimal code to pass.

Application / Library Repositories

Platform / Kubernetes Repositories

For platform engineering work, ksail provides the build → run → publish loop and Testkube runs the actual test suites inside the cluster:

Platform lifecycle commands:

Code Quality Gates (CI)

Every pull request must pass all linting and scanning checks defined in the Testing section. For application / library repositories, additionally:

• No code coverage regression — coverage must not decrease compared to the base branch.
• No benchmark regression — benchmark results must not regress compared to the base branch.

Problem Solving

• Fix at the root cause — never patch symptoms. Trace every bug or failure to its origin and fix it there.
• Workarounds are always temporary — if a workaround is unavoidable, mark it clearly (e.g. // WORKAROUND: comment with a linked issue) and schedule its removal.
• Upstream first — when a fix belongs in a dependency or upstream project, contribute it there. Only carry a local patch until the upstream change is released.

Libraries

Prefer popular, well-maintained third-party libraries over writing custom implementations. Only roll your own when no suitable library exists or when the dependency would be disproportionately heavy.

Refactoring & Design

Follow https://refactoring.guru guidelines for refactoring techniques and design patterns.

Branching & Flow

Use GitHub Flow:

1. Create a feature branch from main.
2. Open a pull request.
3. Pass all CI checks.
4. Merge via merge queue (merge_group) when the repository is configured for it; otherwise merge the pull request normally.

CI/CD Pipeline

Each repository has two core workflow files — ci.yaml and cd.yaml — plus a thin release.yaml that calls a reusable workflow (see Releases). Reusable logic is extracted into local GitHub Actions under .github/actions/:

• Composite actions — for simple, self-contained steps.
• TypeScript actions — for anything complex, because they are locally testable and avoid hard-to-read bash embedded in YAML.

Application / Library Repositories

Platform / Kubernetes Repositories

Releases

Releases are automated via the devantler-tech/actions/.github/workflows/create-release.yaml reusable workflow. It runs semantic-release on push to main, calculates the next semver from conventional commit history, and creates the tag + GitHub release — which in turn triggers the CD pipeline above.

For application publishing, always use upstream releasers — e.g. GoReleaser for Go or dotnet-releaser for .NET — rather than hand-rolling publish scripts.

Data-Driven Improvement

• Use benchmarking data to guide performance improvements — don't optimise without numbers.
• Use code coverage data to guide where to add tests — target uncovered paths, not a vanity percentage.

Reference Implementations

• devantler-tech/ksail — Go CLI built with TDD, full CI/CD pipeline, benchmarks, and E2E system tests in GitHub Actions.
• devantler-tech/platform — Kubernetes platform using ksail for init → create → push OCI workflow, with progressive CI (Docker → Hetzner staging → Hetzner prod).