Best practices for AI-executed issues: Linear issue structure, reviewing plans, and adding a spec layer?

[ouzhou]

Hatice dispatches agents directly from Linear issues. However, when the agent decides the implementation path and testing strategy autonomously, it can feel difficult for humans to review or control the plan before execution.

I have a few questions:

Are there recommended best practices for structuring Linear issues that will be executed by agents?
For example: requirements, constraints, and clear acceptance criteria.

Is there a recommended workflow for reviewing the technical approach and testing strategy before the agent starts coding?

Has anyone experimented with adding a specification layer before issues (e.g. OpenSpec / design.md), such as:

Spec → Task Breakdown → Linear Issues → Hatice Agents

This would allow humans to review the design and testing strategy before agents start implementation.

Curious how others approach this in agent-driven development workflows.

[mksglu]

Great questions @ouzhou — these are exactly the right things to think about when running agents at scale. Here's how Hatice's architecture already supports each of these patterns, and how you can structure your workflow.

1. Structuring Linear Issues for Agent Execution

The agent receives {{ issue.title }} and {{ issue.description }} via the LiquidJS prompt template in WORKFLOW.md. This means the issue description IS the specification — agents interpret it literally. Structure it accordingly:

## Requirements
- User can filter dashboard by date range
- Default range: last 7 days
- URL params sync with filter state

## Constraints
- No new dependencies
- Must work with existing DatePicker component
- Response time < 200ms for filtered queries

## Acceptance Criteria
- [ ] Unit tests for date range validation
- [ ] Integration test for URL param sync
- [ ] Existing tests still pass

The agent also reads .claude/CLAUDE.md in the workspace — this is where you encode TDD methodology, architectural constraints, and coding conventions. Every agent follows these rules automatically, regardless of the issue content.

2. Reviewing Before Agent Execution

Hatice's activeStates config controls which issue states trigger dispatch. Use this as your gate:

tracker:
  activeStates: ["Ready for Agent"]  # NOT "Todo" — only dispatch reviewed issues
  terminalStates: ["Done", "Cancelled"]

This enables a human review workflow:

Author writes issue → "Backlog"
Tech lead reviews spec → moves to "Ready for Agent"  
Hatice polls → picks up "Ready for Agent" → dispatches agent
Agent completes → opens PR → human reviews code

The agent never touches issues in "Backlog" or "In Review" — only activeStates trigger dispatch. This is your control gate.

3. Spec Layer (Spec → Tasks → Issues → Agents)

This is a workflow pattern that Hatice supports but doesn't enforce. The recommended approach:

Option A — Spec in the issue itself (simpler):
Put the full spec (design decisions, testing strategy, edge cases) directly in the Linear issue description. The agent reads it all via {{ issue.description }}. One issue = one spec = one agent.

Option B — Spec as a parent issue (for larger features):

1. Create a parent issue with the full design spec
2. Break it into child issues, each referencing the parent
3. Set child issues to "Ready for Agent" after spec review
4. Hatice dispatches agents for each child independently

You can also use the hooks.afterCreate config to inject spec files into the workspace:

hooks:
  afterCreate: "git clone <repo> . && cp /specs/$(echo $HATICE_ISSUE_ID).md ./SPEC.md"

Then reference it in your prompt template:

Read SPEC.md for the full design specification before starting implementation.
{{ issue.description }}

Key Architectural Points

• maxTurns — Limits how many turns an agent can take. Set lower (e.g., 5) for well-scoped issues, higher for complex ones.
• retryOnNormalExit: false — Agent completes and stops. Set to true if you want iterative refinement.
• .claude/CLAUDE.md — Your most powerful control mechanism. This file defines TDD rules, forbidden patterns, review checklists. Every agent reads it before starting.
• allowedTools / disallowedTools — Restrict what tools agents can use (e.g., prevent git push if you want PR-only workflow).

The philosophy: humans write specifications, agents write code. The clearer your spec (issue description + CLAUDE.md), the better the output. Hatice handles the orchestration — dispatch, retry, reconciliation, observability — so you can focus on specification quality.