# conduct-spec - Transform intent into specification

You are an AI agent using Conduct v0.2 to transform user intent into a structured specification.

## Your Task

Transform the user's request into a complete, actionable spec that follows the Conduct specification format.

## Steps

### 1. Understand the Intent

Read and clarify the user's request:
- What problem are they trying to solve?
- What's the scope (simple/medium/complex/epic)?
- Are there any constraints or requirements?
- Is there an external reference (GitHub issue, Linear ticket, etc.)?

### 2. Query Memory

Check if related work exists:

```bash
conduct list --specs
conduct list --features
```

Look for:
- Similar past specs
- Related features that might be affected
- Existing patterns to follow

### 3. Determine Structure

Choose spec format based on complexity:

**Single-file spec** (< 500 lines, simple/medium):
```
_conduct/specs/{id}.v0.spec.md
```

**Multi-file spec** (> 500 lines, complex/epic):
```
_conduct/specs/{id}/
├── spec.md           # Overview (REQUIRED)
├── architecture.md   # System design
├── database.md       # Schema details
├── api.md            # API contracts
└── ...
```

### 4. Write the Spec

Create the spec file(s) with this structure:

```markdown
# Spec {id}: {Title}

## Meta
- **Spec ID:** {id}
- **Version:** 0
- **Status:** pending
- **LOE:** simple|medium|complex|epic
- **Agent:** {your-name}
- **Created:** {ISO-timestamp}
- **Source:** prompt|file|github|linear|url
- **Source Ref:** {url-if-applicable}

## What
{Clear description of what needs to be built}

## Why
{Problem being solved, business value}

## How
{High-level approach, key decisions}

## Breakdown
{Detailed breakdown of work, acceptance criteria}

## Success Criteria
{How we know it's done}

## Dependencies
{External dependencies, blockers}
```

### 5. Preview with Dry-Run

Always preview before creating:

```bash
conduct spec create _conduct/specs/{id}.v0.spec.md --dry-run
```

This shows:
- Validation results
- Any warnings
- What will be created

### 6. Save to Memory

Create the spec via API:

```bash
conduct spec create _conduct/specs/{id}.v0.spec.md \
  --spec-id {id} \
  --status pending \
  --agent {your-name}
```

The backend automatically:
- Stores in database
- Associates with project
- Makes available to team

### 7. Link to Issues (Optional)

If there's a GitHub/Linear issue, include in spec metadata:

```markdown
## Meta
- **Source:** github
- **Source Ref:** https://github.com/org/repo/issues/123
```

The backend tracks this connection.

## Output

Present the spec to the user and confirm:

1. **Spec location**: Where the spec was saved
2. **LOE estimate**: How much work this represents
3. **Next steps**: How to proceed with implementation
4. **Memory status**: Confirmation that spec is saved to backend

## Example

```
✅ Spec Created: AUTH-001

📊 Estimate: Complex (20-40 hours)

🔗 Links:
  • GitHub Issue: #123
  • Features: auth, user-profile

📝 Next Steps:
  1. Review the spec: conduct spec get AUTH-001
  2. Start implementation: conduct-run
  3. Verify when done: conduct-check

💾 Memory: Saved to backend (team can access)
```

## Quick Reference

```bash
# Always preview first
conduct spec create spec.md --dry-run

# Create the spec
conduct spec create spec.md --spec-id AUTH-001

# View the spec
conduct spec get AUTH-001

# List all specs
conduct spec list

# Update status
conduct spec update AUTH-001 --status in-progress

# Delete if needed
conduct spec delete AUTH-001
```

## Notes

- Always use `--dry-run` first to preview
- Query memory first: `conduct list --specs`
- For external issues, fetch the content first
- Use LOE appropriately (don't over/under-estimate)
- Link to relevant features when known
- Keep specs actionable and clear
- Backend handles storage, you focus on content
- Team members can immediately see your specs