Agent skill
intent-sync
After implementation is complete and tests pass, sync confirmed details back to Intent. Captures finalized interfaces, data structures, naming conventions, and architecture decisions. Use after development is done and user confirms the implementation.
Install this agent skill to your Project
npx add-skill https://github.com/ArcBlock/idd/tree/main/skills/intent-sync
SKILL.md
Intent Sync
Synchronize implementation details back to Intent after development is complete. This makes Intent the true single source of truth.
When to Use
Use /intent-sync when:
- Implementation is complete
- All tests pass
- User has confirmed the implementation works
- You want to capture the finalized design in Intent
What Gets Synced Back
During implementation, many details get finalized that weren't specified in the original Intent:
| Category | Examples |
|---|---|
| Interfaces | API endpoints, function signatures, protocol definitions |
| Data Structures | Schema definitions, type definitions, model structures |
| Naming | Final class names, function names, variable conventions |
| Architecture | Module boundaries, dependency directions, layer structure |
| Configuration | Environment variables, config file formats, defaults |
| Error Handling | Error codes, error message formats, recovery strategies |
Workflow
User confirms implementation is done
↓
Read original Intent file
↓
Scan implemented code for:
- Public interfaces
- Data structures
- Key naming conventions
- Architecture patterns
↓
Compare with Intent
↓
Identify gaps/differences
↓
Present changes for approval
↓
Update Intent with confirmed details
↓
Mark synced sections with timestamp
Sync Process
Step 1: Gather Implementation Facts
Scan the codebase for finalized details:
Code Analysis:
├── Public APIs
│ ├── Endpoints (REST/GraphQL/RPC)
│ ├── Function signatures
│ └── Event definitions
├── Data Models
│ ├── Database schemas
│ ├── Type definitions
│ └── Config structures
├── Architecture
│ ├── Module structure
│ ├── Dependency graph
│ └── Layer boundaries
└── Conventions
├── Naming patterns
├── Error formats
└── Logging standards
Step 2: Compare with Intent
Identify what's new or different:
| Status | Meaning | Action |
|---|---|---|
| New | Not in original Intent | Add to Intent |
| Changed | Different from Intent | Update Intent |
| Confirmed | Matches Intent | Mark as implemented |
| Removed | In Intent but not implemented | Remove or mark deferred |
Step 3: Present for Approval
Use AskUserQuestion to confirm changes:
"The following details were finalized during implementation.
Should I sync them back to Intent?"
Interfaces:
- [x] POST /api/users - Create user (new)
- [x] UserSchema: added 'createdAt' field (changed)
Data Structures:
- [x] Config now uses YAML instead of JSON (changed)
Naming:
- [x] Service class renamed to UserService (changed)
Step 4: Update Intent
Add a new section or update existing sections:
## Finalized Implementation Details
> Synced on: YYYY-MM-DD
> From: [commit hash or version]
### API Interfaces
| Endpoint | Method | Request | Response |
|----------|--------|---------|----------|
| /api/users | POST | `{name, email}` | `{id, name, email, createdAt}` |
| /api/users/:id | GET | - | `{id, name, email, createdAt}` |
### Data Structures
\`\`\`typescript
interface User {
id: string;
name: string;
email: string;
createdAt: Date;
}
\`\`\`
### Module Structure
\`\`\`
src/
├── api/
│ └── users.ts # User endpoints
├── services/
│ └── UserService.ts # Business logic
├── models/
│ └── User.ts # Data model
└── config/
└── config.yaml # Configuration
\`\`\`
### Key Decisions Confirmed
| Decision | Final Choice | Rationale |
|----------|--------------|-----------|
| Config format | YAML | Better readability for nested config |
| ID generation | UUID v4 | Standard, no coordination needed |
Output Format
The sync adds or updates these Intent sections:
New Section: ## Finalized Implementation Details
Contains:
- Sync timestamp
- Source reference (commit/version)
- Concrete interfaces
- Concrete data structures
- Final module structure
- Confirmed decisions
Updated Existing Sections
- Architecture diagrams updated to reflect reality
- Data contracts updated with actual schemas
- API specifications updated with real endpoints
Sync Markers
Use markers to indicate sync status:
## API Design
> [!SYNCED] Last synced: 2024-01-15 from commit abc123
### Endpoints
...
Or in tables:
| Component | Status | Last Synced |
|---|---|---|
| User API | SYNCED | 2024-01-15 |
| Auth API | DRAFT | - |
Integration with Other Skills
/intent-interview # Create Intent (initial)
↓
/intent-review # Approve Intent
↓
/intent-plan # Generate execution plan
↓
[Execute: TDD cycles]
↓
/intent-sync # Write back confirmed details (THIS SKILL)
↓
/intent-check # Verify consistency
Best Practices
- Sync after stability: Don't sync during active development; wait for confirmation
- Preserve original intent: Keep original design rationale, add implementation details
- Be specific: Include actual types, actual endpoints, actual names
- Version reference: Always note which code version was synced
- Incremental sync: Can sync multiple times as features stabilize
Example Session
User: Implementation is done, tests pass. Please sync back to Intent.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
ArcBlock/idd
intent-build-now
Start implementation from Intent. Validates Intent completeness, then either delegates to TaskSwarm (if available) or executes TDD phases directly. Use when you have an Intent ready and want to start building.
ArcBlock/idd
intent-story
Share your IDD adoption story. Through structured interviewing, create blog posts about Intent-Driven Development experiences, lessons learned, and best practices. Supports multiple languages and formats.
ArcBlock/idd
intent-critique
Critical review of Intent design quality. Checks for over-engineering, YAGNI violations, premature abstraction, and simplification opportunities. Uses interactive discussion to refine design decisions.
ArcBlock/idd
intent-changes
Manage structured change proposals for design documents with PR-like review experience. Use /intent-changes start <file> to begin, /intent-changes propose to suggest changes, /intent-changes accept/reject to decide, /intent-changes finalize to apply.
ArcBlock/idd
intent-assess
Assess if IDD fits your project and learn about Intent-Driven Development. Use /intent-assess to evaluate project suitability or /intent-assess --learn for IDD education.
ArcBlock/idd
intent-interview
Didn't find tool you were looking for?