Work item blueprint pattern
The work item blueprint pattern gives Port a dedicated entity for tracking AI-assisted development. It separates workflow execution state from origin tickets (Jira, Linear, or ADO), so AI agents have the context they need without cluttering your ticketing system.
Adapt the stages, scorecards, and AI integrations to match your organization's workflow.
The problem with thin tickets
A ticket with a title and a short description is not enough for a human to start safely. It is definitely not enough for an AI agent.
To make a ticket actionable, you need the service it affects, the team that owns it, the service's tier and blast radius, relevant previous specs, and a judgment on whether AI delegation is appropriate.
Adding all of this directly to the Jira issue creates tight coupling between your AI logic and an external system, clutters your ticketing UI, and makes the data hard to query. The work item pattern solves this by creating a dedicated Port entity that aggregates context from your catalog and tracks workflow state independently.
The entity model
A work_item entity maintains a relation to the origin ticket while connecting to everything the workflow needs:
| Relation | What it provides |
|---|---|
| Origin ticket (Jira/Linear/ADO) | The raw requirements. |
| Service | Tier, blast radius, active incidents. |
| Team | Owner, escalation path. |
| Repository | Code patterns, recent changes. |
| Pull request | Implementation status. |
| Deployment | Production verification. |
AI agents access this context through mirror properties. The work item does not store the data itself - it points to entities already in your catalog, so everything stays in sync automatically.
The five-stage workflow
Work items progress through five stages, each with specific requirements and AI integration points:
| Stage | What happens | AI role |
|---|---|---|
| Draft | Ticket created, minimal information. | Suggest initial categorization. |
| Plan | Context assembled, routing decision made. | Generate PRD, tech spec, routing narrative. |
| Develop | Code implementation in progress. | Generate code, respond to review feedback. |
| Deploy | PR merged, blast radius evaluated. | Assess deployment risk and timing. |
| Completed | Production deployment confirmed. | Update documentation. |
Scorecard rules act as gates between stages. Work items cannot advance until the requirements for the next stage are met.
The routing decision
The routing decision is the key output of the Plan stage. It answers one question: is this work item ready for AI delegation?
Two layers evaluate it:
Deterministic scorecards - Your platform team defines rules based on objective criteria:
- Service tier (T1 services are excluded).
- Blast radius (high-impact changes route to humans).
- Priority (critical items bypass AI delegation).
- Active incidents (blocks delegation while an incident is open).
AI narrative assessment - Port AI generates a written explanation of the routing decision, grounded in the PRD and tech spec. The engineer gets context for the decision, not just a pass/fail result.
The engineer then acts on one of three options: Delegate to Claude Code, Iterate on PRD, or Continue in IDE. That response writes back to the Port entity. Routing decisions become measurable data, not individual judgment calls.
AI augmentation levels
Each work item has an AI augmentation level that defines how much of the implementation an agent handles:
| Level | Description |
|---|---|
| Human | No AI involvement. Engineer implements end to end. |
| AI-assisted | AI suggests approaches. Human implements. |
| AI-led | AI implements. Human reviews and approves. |
| Autonomous | AI implements and deploys with monitoring. Human approves before production. |
The augmentation level is set during the Plan stage and factors into the routing decision.
Scorecard-driven progression
Scorecards evaluate work item properties and relations to determine the current stage. Each transition has specific requirements:
- Draft to Plan - Owner assigned, priority set, AI augmentation level defined.
- Plan to Develop - Plan approved by a human, PR created.
- Develop to Deploy - PR merged.
- Deploy to Completed - Deployment successful in production.
This keeps progression logic in Port, not hard-coded in Jira workflows or GitHub Actions. You can change requirements without touching external systems.
Customizing for your workflow
The five-stage pattern works for most teams. You can adapt it:
- Stage names - Rename stages to match your terminology ("Refinement", "In Progress", "Release").
- Progression rules - Add a testing stage between Develop and Deploy, or remove plan approval for low-priority items.
- Relations - Connect to entities relevant to your workflow: design documents, testing environments, feature flags.
- Routing rules - Adjust the scorecard criteria that gate AI delegation to match your organization's risk tolerance.
Implementation
The work item blueprint implementation guide covers technical setup including:
- Blueprint configuration with properties and relations.
- Scorecard rules for each stage transition.
- Self-service actions for stage progression.
- AI agent integration points.
- Example JSON configurations.