Practical guide

Build internal tools with AI: from workflow to working app

Turn a recurring business workflow into a clear application brief, follow reviewed development and decide what a useful first result must demonstrate.

Your working documentWorkflow brief, acceptance checklist and first-change note.

Illustrative workflow diagram

Illustrative working methodFrom a handoff to a useful result.
Equipment request01 / The workAvery needs a standing desk.

A request, a separate approval, a recorded handover.

02 / DefineWorkflow briefPeople · records · authority
03 / BuildReviewed changeCandidate · review · correction
04 / TryAcceptance checksPermitted · refused · preserved
Delivered, with an asset tag.First-change note: keep earlier work protected.

Authored illustration of workflow rules and responsibilities.

Prepared with AI for the Soda OS website. Public maintainer: @vinchdev on X/Twitter. Suggest a correction on GitHub.

Worked workflows, briefs and acceptance scenarios are authored illustrations, not customer outcomes or a recording of a completed factory run. The linked stories own their example rules; the handbooks own exact product procedures.

01Business direction

Choose the right problem

Start with a recurring handoff, an unclear rule or records scattered across messages and spreadsheets. Ask the people doing the work where a request loses its owner and how they know it is finished.

A spreadsheet may already be sufficient. A configured existing tool may fit. Build when a clear business need warrants its ongoing development and operation, rather than because AI can produce a screen.

Our illustrative thread is equipment requests. Operations needs a catalogue, a separate approval and a record that approved equipment reached the requester. This is an example to adapt, not a bundled application or a customer result.

Illustrative workflow diagram

Start with a need, then choose the tool.
Where does the handoff fail?
Keep a spreadsheetTracking is enough.Configure a toolExisting controls fit.Build an appOwned rules justify the work.

Authored illustration of workflow rules and responsibilities.

02First-version scope

Bound the first version

Name the business owner, intended users and useful end state before asking for implementation. Keep the first workflow small enough for those people to review together. Record essential connections and access prerequisites; ask the responsible people to settle open decisions.

Operations owns this first result: Avery requests a standing desk, Alex approves as a separate reviewer, and a coordinator records delivery. Purchasing, supplier payments and device provisioning are separate requirements to discuss if needed.

A reviewable first outcome
Owner
Operations: requirements and business acceptance.
People
Employee requester, reviewer and Operations coordinator.
Result
An approved catalogue request with recorded delivery.
Connections
Resolve account, catalogue and asset-system needs with IT.
Open question
Who maintains the catalogue and records a valid handover?
03Application permissions

Define records, actions and authority

Describe whose record an action touches, who may perform it and which state permits it. A role label alone is insufficient: a reviewer must still be refused permission to approve their own request.

Use Requested → Approved → Delivered. Employees read their own requests; reviewer and coordinator roles grant queue access. Protect the item, reason and requester after approval and the delivery facts after completion.

First-version application authority

ActorRequester

Record and action
Create and edit own request
Guard
Edit only while awaiting approval.

ActorReviewer

Record and action
Approve another person’s eligible request
Guard
Active catalogue item; no self-approval or repeated approval.

ActorCoordinator

Record and action
Record delivery
Guard
Approved request and nonempty asset tag.
04Your working document

Write a reviewable brief

Give AI outcomes, records, rules and concrete successful and refused examples. Resolve consequential questions with the people who own them. A prompt cannot confer application access or settle company policy.

Use the filled example to see the level of detail, then select or copy the blank brief. Keep both as ordinary text that your department and technical counterpart can review together.

Workflow briefWorked example

Filled equipment brief

An illustrative equipment workflow, from business direction to acceptance and its next change.

Direction

Workflow
Equipment requests: catalogue → request → approval → delivery.
Business owner
Operations owns the rules and accepts the useful result.
Recurring problem
Requests arrive in messages; approval and handover are difficult to follow.

People, records and rules

Users
Employee requester, authorised reviewer, Operations coordinator.
Records
Catalogue item; request with item, reason, requester and status; approval actor/time; delivery time and asset tag.
Actions and visibility
Employees create and follow their own requests and edit while awaiting approval. Reviewers and coordinators see the queue through their roles. Reviewers approve another person’s eligible request; coordinators maintain the catalogue and record delivery.
Useful first outcome
Avery requests a standing desk; Alex approves; Operations records delivery with a nonempty asset tag. Avery sees the handover.
Exceptions and refusals
Refuse self-approval, repeated approval, delivery before approval and an empty asset tag. Protect item, reason and requester after approval, and completed delivery fields.

Operation and open decisions

Required connections
Agree account access and any catalogue or asset-system connection with IT; no external integration is assumed.
Operating owner
Name an application operator with IT before team use; agree access, service and data responsibilities.
Unresolved decisions
Who maintains the catalogue, who records delivery, and what evidence is needed for handover?

Acceptance

Permitted acceptance case
Avery submits; Alex, an authorised different person, approves; a coordinator records delivery. Reload and confirm the saved request, approval and delivery remain visible to authorised people.
Refused acceptance case
A reviewer cannot approve their own request; an unrelated ordinary employee cannot read Avery’s request.

Next change

Anticipated later change
For newly created requests, add Finance approval above €1,000 after ordinary approval. Exactly €1,000 keeps the ordinary path.
Existing work to preserve
Earlier requests, including pending ones, retain their original workflow and decisions.
Plain text for manual copying 15 fields
Filled equipment brief

Workflow: Equipment requests: catalogue → request → approval → delivery.

Business owner: Operations owns the rules and accepts the useful result.

Recurring problem: Requests arrive in messages; approval and handover are difficult to follow.

Users: Employee requester, authorised reviewer, Operations coordinator.

Records: Catalogue item; request with item, reason, requester and status; approval actor/time; delivery time and asset tag.

Actions and visibility: Employees create and follow their own requests and edit while awaiting approval. Reviewers and coordinators see the queue through their roles. Reviewers approve another person’s eligible request; coordinators maintain the catalogue and record delivery.

Useful first outcome: Avery requests a standing desk; Alex approves; Operations records delivery with a nonempty asset tag. Avery sees the handover.

Exceptions and refusals: Refuse self-approval, repeated approval, delivery before approval and an empty asset tag. Protect item, reason and requester after approval, and completed delivery fields.

Required connections: Agree account access and any catalogue or asset-system connection with IT; no external integration is assumed.

Operating owner: Name an application operator with IT before team use; agree access, service and data responsibilities.

Unresolved decisions: Who maintains the catalogue, who records delivery, and what evidence is needed for handover?

Permitted acceptance case: Avery submits; Alex, an authorised different person, approves; a coordinator records delivery. Reload and confirm the saved request, approval and delivery remain visible to authorised people.

Refused acceptance case: A reviewer cannot approve their own request; an unrelated ordinary employee cannot read Avery’s request.

Anticipated later change: For newly created requests, add Finance approval above €1,000 after ordinary approval. Exactly €1,000 keeps the ordinary path.

Existing work to preserve: Earlier requests, including pending ones, retain their original workflow and decisions.
Workflow briefReusable template

Blank workflow brief

Copy this template to agree your workflow, rules, acceptance cases and next change.

Direction

Workflow
Name the recurring workflow.
Business owner
Who owns requirements and acceptance?
Recurring problem
Describe the handoff, unclear rule or fragmented record.

People, records and rules

Users
List people and application roles.
Records
Name the records and relationships.
Actions and visibility
Who sees whose records and can do what, in which state?
Useful first outcome
Describe the completed result people can try.
Exceptions and refused actions
Include protected fields and completed decisions.

Operation and open decisions

Required connections
Name essential integrations and access prerequisites.
Operating owner
Name service, access and data responsibilities.
Unresolved decisions
List questions and the people authorised to answer them.

Acceptance

Permitted acceptance case
Given an actor and record state, what succeeds?
Refused acceptance case
What must fail, and what must remain unchanged?

Next change

Anticipated later change
Name one likely rule change.
Existing work to preserve
Describe the records, permissions and history to retain.
Plain text for manual copying 15 fields
Blank workflow brief

Workflow: [Name the recurring workflow.]

Business owner: [Who owns requirements and acceptance?]

Recurring problem: [Describe the handoff, unclear rule or fragmented record.]

Users: [List people and application roles.]

Records: [Name the records and relationships.]

Actions and visibility: [Who sees whose records and can do what, in which state?]

Useful first outcome: [Describe the completed result people can try.]

Exceptions and refused actions: [Include protected fields and completed decisions.]

Required connections: [Name essential integrations and access prerequisites.]

Operating owner: [Name service, access and data responsibilities.]

Unresolved decisions: [List questions and the people authorised to answer them.]

Permitted acceptance case: [Given an actor and record state, what succeeds?]

Refused acceptance case: [What must fail, and what must remain unchanged?]

Anticipated later change: [Name one likely rule change.]

Existing work to preserve: [Describe the records, permissions and history to retain.]
05Soda OS · reviewed development

Build through reviewed changes

In Soda OS, accepted direction becomes native Forgejo work items and dependencies: records and access, guarded approval and delivery, then connected screens and checks. Coding agents work in a persistent Project with authorised access and present a candidate with evidence; Soda OS publishes the pull request.

A separate review session examines the exact candidate. An illustrative finding is that checking only the reviewer role permits self-approval. The coding role corrects the guard and checks the required outcomes. Repository policy and current evidence govern integration, including human approval where required.

People clarify requirements and developers can intervene using their preferred computers, editors, terminals and SSH access. A run ending does not destroy the Project or unrelated work. This development continuity does not establish how an application runtime handles storage changes.

CanLang can provide records, permissions, workflows and connected interfaces for this example. It is optional in Soda OS and independently usable; the method also applies to other repositories.

  1. Agree direction

    Agree direction and unresolved questions.

  2. Organise the work

    Create native work items with prerequisites.

  3. Implement

    Code in the persistent Project.

  4. Review the candidate

    Review the exact candidate and its evidence.

  5. Correct and recheck

    Correct findings and check again.

  6. Integrate

    Integrate under repository policy; decide application deployment separately.

06Department acceptance

Try the running application

Business acceptance checks whether the application supports the agreed work. Code review checks the implementation. An equipment approval inside the app is a third, separate business action. None substitutes for the others.

Try permitted and refused actions as the relevant people, not just as an administrator. Check visibility, saved records and the completed outcome. Record the version and environment you tried; a screenshot or a merged change alone does not establish acceptance.

  1. Request and visibility

    Permit Avery to select active catalogue equipment, give a reason and follow the request; refuse access for an unrelated ordinary employee.

  2. Separate approval

    Permit an authorised reviewer to approve another person’s eligible request; refuse self-approval and a second approval.

  3. Protected request

    Refuse rewriting the equipment selection, reason or requester after approval.

  4. Delivery guard

    Permit a coordinator to record delivery after approval with a nonempty asset tag; refuse early delivery and an empty tag.

  5. Completed record

    Confirm delivery status, time and asset tag are recorded and completed delivery details cannot be rewritten.

  6. Saved work

    Reload the running application and check the saved records and visibility. Record this browser-reload result separately from any rebuild or deployment check.

07Company operation

Decide how it will run for the team

Name the application operator before team use. Agree who manages access, service availability, application data, backup and recovery, updates and required connections. The department retains ownership of requirements and acceptance; IT and platform administrators retain infrastructure, accounts and policy responsibilities.

Integration and production deployment are separate actions. Follow the instructions for the chosen application and environment, then check the deployed workflow with its intended users. Agree the continuing operating responsibilities rather than assuming a preview is a company service.

Illustrative workflow diagram

Agree both owners before team use.
DepartmentRequirementsBusiness acceptance
Application operatorAccess · data · availabilityBackup · updates · recovery

Reviewed integration ≠ production deployment

Authored illustration of workflow rules and responsibilities.

08Continuing change

Ask for the next change

After the first outcome is useful, write the next rule and decide what it means for existing work. For equipment, Finance introduces an additional approval for higher-value new requests. The same application and Project continue through a newly agreed and reviewed change.

Onboarding illustrates a different policy: existing tasks keep explicit dates until HR deliberately converts unfinished work. A start-date change moves only unfinished relative tasks after preview and confirmation. Fixed dates and completed records remain protected. Choose the preservation rule for each change.

Initial rule
An authorised reviewer approves another person’s request before Operations records delivery.
New rule
For new requests above €1,000, ordinary approval locks the reviewed positive EUR amount and moves the request to Awaiting Finance. Finance approval then permits delivery. Exactly €1,000 follows the ordinary path. The Finance approver differs from both requester and initial approver, even when people hold multiple roles.
What stays protected
Earlier requests, including pending ones, retain their original workflow and decisions. Display the applicable policy. Refuse repeated decisions, changes to the reviewed amount, and delivery before every required approval.
Change briefWorked example

Filled first-change note

An illustrative next-change note connecting the Finance rule with protected work, checks and operation.

Reason and new rule

Reason
Add financial control for higher-value new equipment requests.
Rule
For new requests above €1,000, ordinary approval locks the reviewed positive EUR amount and moves the request to Awaiting Finance. Finance approval then permits delivery. Exactly €1,000 follows the ordinary path. The Finance approver differs from both requester and initial approver, even when people hold multiple roles.

Existing work

Existing work
Earlier requests, including pending ones, retain their original workflow and decisions. Display the applicable policy. Refuse repeated decisions, changes to the reviewed amount, and delivery before every required approval.

Checks and operation

Checks
Try below, exactly at and above €1,000; refuse requester/initial-reviewer Finance approval and early delivery; preserve earlier pending and completed requests.
Operation
Agree policy effective point, applicable-policy display, application operator and deployment checks before rollout.
Plain text for manual copying 5 fields
Filled first-change note

Reason: Add financial control for higher-value new equipment requests.

Rule: For new requests above €1,000, ordinary approval locks the reviewed positive EUR amount and moves the request to Awaiting Finance. Finance approval then permits delivery. Exactly €1,000 follows the ordinary path. The Finance approver differs from both requester and initial approver, even when people hold multiple roles.

Existing work: Earlier requests, including pending ones, retain their original workflow and decisions. Display the applicable policy. Refuse repeated decisions, changes to the reviewed amount, and delivery before every required approval.

Checks: Try below, exactly at and above €1,000; refuse requester/initial-reviewer Finance approval and early delivery; preserve earlier pending and completed requests.

Operation: Agree policy effective point, applicable-policy display, application operator and deployment checks before rollout.

  1. Changed outcome

    Agree the changed outcome and existing-record policy.

  2. Boundary cases

    Review permitted, refused and boundary cases.

  3. Protected history

    Confirm protected history and permissions.

  4. Running result

    Name the operator and review the running result after deployment.