How to Run an Agentic Software Engineering Workflow

Agentic Engineering is a role-based operating model for shipping software changes. It is not a replacement for requirements or technical design. It answers a different question: once work is approved, how do the right roles move it from an idea to a tested, reviewable merge?

This guide shows how to implement the workflow in a Django repository using concrete artifacts, handoffs, task boundaries, and validation commands.

Create a work-item contract

Start each feature with a small configuration record. It should identify the feature, repository, implementation mode, review triggers, and required documents:

feature: inventory-analysis
repository: codingbowl_django
implementation_mode: Auto
reviews:
  ux: true
  database_architect: true
required_documents:
  - requirements.md
  - functional-spec.md
  - implementation-plan.md

Auto means the assigned engineer may make scoped changes and run validation. Manual means the engineer can inspect the repository and prepare patches, but the user applies the changes. Recording this choice avoids accidental changes outside the task’s authority.

Use artifacts as handoff contracts

The first roles should produce files that later roles can rely on:

_docs/inventory-analysis/
├── requirements.md
├── functional-spec.md
├── architecture.md
├── implementation-plan.md
├── wireframes/
└── request-flow.md

The Business Analyst turns raw stakeholder input into requirements, assumptions, open questions, and dependencies. The Product Manager approves the requirements. The functional specification maps each requirement to user behavior, rules, states, and acceptance criteria. The Technical Lead adds architecture, task order, and validation strategy.

Avoid a handoff that says only “please review.” Make the requested result explicit:

## Handoff: Business Analyst -> Product Manager

Deliverables:
- requirements.md
- open questions section
- dependency list

Decision requested:
- Approve the requirement set or identify changes by requirement ID.

Trigger specialist reviews from the change surface

Do not require every specialist on every task. Trigger review based on what the task changes.

Request UI/UX review when the feature changes layout, interaction, accessibility, responsive behavior, navigation, or user-facing states. Request Database Architect review when it changes models, migrations, indexes, constraints, backfills, data integrity, or migration-sensitive performance.

The database review should produce a machine-readable outcome in the document:

Database review: APPROVED
Migration risk: low
Indexes: existing composite index is sufficient
Backfill: not required
Rollback: migration is reversible

If the result is BLOCKED, the Technical Lead should not assign implementation until the blocking question is resolved.

Groom tasks until an engineer can execute them

A groomed task contains a single objective, affected files or layers, dependencies, constraints, acceptance criteria, focused tests, and a definition of done:

## Task INV-12 — Add warehouse filter to inventory list

Objective: filter the list and summary metrics by the selected warehouse.

Dependencies: functional-spec §3; DB review APPROVED.

Acceptance criteria:
- valid warehouse IDs filter both rows and summary values
- unauthorized warehouses return the existing permission response
- an unknown warehouse shows the unavailable state
- the selected filter survives pagination

Focused validation:
- `python manage.py test inventory.tests.test_views.InventoryListTests`
- manual request-flow check for authorized and unauthorized users

If a task needs two engineers or has unrelated acceptance criteria, split it before assignment. A small task gives QA a finite surface to verify and gives the Technical Lead a meaningful review boundary.

Make the engineer-to-QA handoff executable

The engineer should provide more than a branch name. Include the changed-file summary, test commands, results, known limitations, and the acceptance-criterion mapping:

## Engineer handoff

Changed:
- `inventory/views.py`
- `inventory/services.py`
- `inventory/tests/test_views.py`

Validation:
- `python manage.py check` — PASS
- `python manage.py test inventory.tests.test_views` — PASS

Known limitation: browser-level responsive check still required.

QA should report one result per criterion rather than a general impression:

| Criterion | Result | Evidence |
|---|---|---|
| Rows filter by warehouse | PASS | test_filter_warehouse |
| Unauthorized warehouse denied | PASS | test_warehouse_permission |
| Pagination preserves filter | FAIL | query parameter lost on next link |

QA reports failures; it does not silently repair the implementation. The assigned engineer resolves the failure, updates the evidence, and requests QA again.

Keep the Git workflow aligned with approval gates

Use a branch and focused commit for the task:

git switch -c feature/inventory-warehouse-filter
python manage.py check
python manage.py test inventory
git add inventory/ _docs/inventory-analysis/
git commit -m "Add warehouse filter to inventory list"

The Technical Lead reviews the diff, test evidence, acceptance-criterion results, and documentation updates. Merge is permitted only after QA reports PASS for every criterion and the Technical Lead records approval. This prevents “the code is ready” from being mistaken for “the work is accepted.”

Close the loop with a request-flow record

After acceptance, document the proven path through Django:

GET /inventory/?warehouse=west
  -> InventoryListView.get()
  -> parse and validate warehouse
  -> WarehouseAccessPolicy.can_view()
  -> InventoryQuery.for_warehouse()
  -> InventorySummary.calculate()
  -> render inventory/list.html

Record the data sources, permission checks, empty and error states, accessibility behavior, and tests that verify the flow. When a future change breaks the path, this record gives the maintainer a map of the behavior that must remain intact.

A lightweight operating rhythm

For a small Django feature, the entire workflow may fit into one working session:

1. Refine the requirement and write acceptance criteria.
2. Decide whether UX or database review is triggered.
3. Approve the functional specification and groom one task.
4. Implement with focused tests.
5. Hand off evidence to QA.
6. Resolve failures and obtain QA PASS.
7. Obtain Technical Lead approval and merge.
8. Update the request-flow record.

The framework scales by adding specialist review and documentation only when the change surface warrants it. Its purpose is not ceremony. Its purpose is to make ownership, evidence, and approval visible at the exact points where software delivery usually becomes ambiguous.

Influence and further reading

This workflow is inspired by Alexey’s approach to AI-native development, especially the use of written specifications as the foundation for coordinating AI-assisted work. I adapted that specifications-first idea into a role-based Django team with Markdown files, a team/ folder, and an Orchestrator role.

Read: AI-Native Development: Specifications by Alexey.

Related: Markdown Operating System: An AI-Native Django Team.