| description | Codifies devantler-tech engineering practices: agent-first development workflow, TDD, CI/CD pipelines, GitHub Flow, code quality gates, and Kubernetes workflows with ksail. Use when filing issues, planning work, setting up projects, configuring CI/CD, writing tests, debugging, or making architectural decisions. |
| license | Apache-2.0 |
| metadata | {"github-path":"ways-of-working","github-ref":"refs/tags/v1.5.0","github-repo":"https://github.com/devantler-tech/agent-skills","github-tree-sha":"219a45e80e25b47cc23dcfed9febd526655e624c"} |
| name | 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:
- 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).
- Plan — create a structured implementation plan from the issue before writing code.
- Implement — execute the plan following the practices in this skill (TDD, quality gates, GitHub Flow, CI/CD).
- 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.
- 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
| Type | Tooling | When to run |
|---|
| Linting | Linters and linting runners (e.g. golangci-lint, eslint, MegaLinter) | CI on every PR |
| Scanning | Security & quality scanners (e.g. CodeQL, Trivy, SonarQube) | CI on every PR |
| Unit tests | SDK test frameworks (e.g. go test, xunit, jest) | CI on every PR |
| Integration tests | SDK test frameworks | CI on every PR |
| E2E / system tests | GitHub Actions workflows that exercise the app/binary/service as an end user would | CI on every PR; move to merge_group if the suite becomes too heavy |
| Benchmark tests | SDK benchmark frameworks (e.g. BenchmarkDotNet, go test -bench) | CI on every PR |
Platform / Kubernetes Repositories
For platform engineering work, ksail provides the build → run → publish loop and Testkube runs the actual test suites inside the cluster:
| Type | Tooling | What it does |
|---|
| Linting | Manifest linters (e.g. kubeconform, kube-linter) | Validate manifests statically — no cluster needed |
| Scanning | Security scanners (e.g. Trivy) | Scan manifests and images for vulnerabilities — no cluster needed |
| Integration tests | Ephemeral local cluster (ksail cluster create) + Testkube | Spin up a Docker cluster, deploy workloads, and run Testkube test suites against them |
| E2E / system tests | Ephemeral or real cluster + Testkube | Deploy to a full environment (local or remote) and run end-to-end Testkube test suites |
Platform lifecycle commands:
| Command | Purpose |
|---|
ksail cluster init | Scaffold a new cluster configuration |
ksail cluster create | Spin up the cluster locally (Docker) or on real infrastructure and verify workloads reconcile |
ksail workload push | Push Kubernetes manifests as OCI artifacts to a container registry |
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:
- Create a feature branch from
main.
- Open a pull request.
- Pass all CI checks.
- 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
| Event | What runs |
|---|
pull_request | Linting, scanning, unit tests, integration tests, E2E tests, benchmarks, coverage & benchmark regression checks. Move E2E to merge_group only if the suite becomes too heavy. |
merge_group | CD to dev environment. |
push to main | Publish artifacts (packages, container images, etc.). |
Semver tag (vX.X.X) | CD to prod environment. |
Platform / Kubernetes Repositories
| Event | What runs |
|---|
pull_request | Linting, scanning, integration tests on an ephemeral local cluster (ksail cluster create + Testkube). Move integration tests to merge_group if the suite becomes too heavy. |
merge_group | CD to dev — deploy to staging infrastructure (e.g. Hetzner). |
Semver tag (vX.X.X) | CD to prod — ksail cluster update, ksail workload push, ksail workload reconcile. |
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).
