cardosofelipe/syndarix
1
0
Fork 0
forked from cardosofelipe/fast-next-template
Code Issues 18 Pull Requests Wiki Activity

[SPIKE-012] Client Approval & Intervention System #12

New Issue
Closed
opened 2025-12-29 03:51:02 +00:00 by cardosofelipe · 1 comment
cardosofelipe commented 2025-12-29 03:51:02 +00:00
Owner
Copy Link

Objective

Design the system for client approvals and interventions at various autonomy levels.

Approval Points

  1. Requirements approval
  2. Architecture approval
  3. Sprint scope approval
  4. PR/code review approval (at FULL_CONTROL level)
  5. Deployment approval

Key Questions

  1. How do we queue approval requests?
  2. How do we notify clients of pending approvals?
  3. How do agents block/wait for approval?
  4. How do we handle approval timeouts?
  5. How do we support "approve with changes" vs "reject"?

Autonomy Level Behavior

  • FULL_CONTROL: Approve most actions
  • MILESTONE: Approve sprint boundaries
  • AUTONOMOUS: Only critical decisions

Research Areas

  • Approval workflow patterns
  • Notification delivery (email, webhook, in-app)
  • Approval queue management
  • Integration with agent waiting states

Expected Deliverables

  • Approval entity and workflow
  • Notification system design
  • Agent waiting/blocking pattern
  • UI mockups for approval interface
  • ADR documenting the approach

Acceptance Criteria

  • Approvals queued and visible to client
  • Notifications sent appropriately
  • Agents wait for approval correctly
  • Different autonomy levels work

Labels

spike, architecture, workflow

## Objective Design the system for client approvals and interventions at various autonomy levels. ## Approval Points 1. Requirements approval 2. Architecture approval 3. Sprint scope approval 4. PR/code review approval (at FULL_CONTROL level) 5. Deployment approval ## Key Questions 1. How do we queue approval requests? 2. How do we notify clients of pending approvals? 3. How do agents block/wait for approval? 4. How do we handle approval timeouts? 5. How do we support "approve with changes" vs "reject"? ## Autonomy Level Behavior - FULL_CONTROL: Approve most actions - MILESTONE: Approve sprint boundaries - AUTONOMOUS: Only critical decisions ## Research Areas - [ ] Approval workflow patterns - [ ] Notification delivery (email, webhook, in-app) - [ ] Approval queue management - [ ] Integration with agent waiting states ## Expected Deliverables - Approval entity and workflow - Notification system design - Agent waiting/blocking pattern - UI mockups for approval interface - ADR documenting the approach ## Acceptance Criteria - [ ] Approvals queued and visible to client - [ ] Notifications sent appropriately - [ ] Agents wait for approval correctly - [ ] Different autonomy levels work ## Labels `spike`, `architecture`, `workflow`
cardosofelipe commented 2025-12-29 12:23:38 +00:00
Author
Owner
Copy Link

SPIKE-012: Client Approval Flow - Research Complete

The spike document has been created at docs/spikes/SPIKE-012-client-approval-flow.md.

Executive Summary

Based on industry research and Syndarix's existing architecture, we recommend a checkpoint-based approval system with the following key components:

Key Recommendations

  1. Queue-Based Approval Pattern - Single queue with priority lanes (CRITICAL, MILESTONE, ROUTINE) aligned with Syndarix's three autonomy levels (FULL_CONTROL, MILESTONE, AUTONOMOUS)

  2. Confidence-Aware Routing - AI decisions with confidence below 85% automatically trigger human review regardless of autonomy level

  3. Batch Approval Support - Efficiency feature for FULL_CONTROL mode users to approve multiple low-risk, routine decisions at once

  4. SSE-Based Notifications - Leverage existing real-time infrastructure (SPIKE-003) for approval alerts

  5. Mobile-First Design - One-touch approve/reject with push notifications for urgent decisions

  6. Flexible Timeout & Escalation - Configurable per project with auto-escalation paths

Database Schema Highlights

  • ApprovalRequest - Core entity for approval checkpoints
  • ApprovalAuditEvent - Immutable audit trail for compliance
  • DelegationRule - Flexible delegation authority
  • EscalationPolicy - Project-level timeout configuration

Approval Categories

Category Use Case Default Timeout
CRITICAL Budget, production deploys 4 hours
MILESTONE Sprint boundaries, architecture 24 hours
ROUTINE PRs, bug fixes 48 hours
UNCERTAINTY Low confidence AI decisions 12 hours
EXPERTISE Agent requests human knowledge 24 hours

Implementation Roadmap

  • Phase 1 (Week 1-2): Database schema, core service, API endpoints
  • Phase 2 (Week 3-4): Workflow integration (sprints, PRs, deploys)
  • Phase 3 (Week 5-6): UI/UX implementation, notifications
  • Phase 4 (Week 7-8): Advanced features (escalation, delegation, audit)

Key Research Sources

Next Steps

  1. Review the full spike document for detailed schema, code examples, and UI mockups
  2. Create implementation tasks based on the 8-week roadmap
  3. Prioritize integration with existing autonomy level configuration (FR-203)

Generated by Claude Code - SPIKE-012 Research

## SPIKE-012: Client Approval Flow - Research Complete The spike document has been created at `docs/spikes/SPIKE-012-client-approval-flow.md`. ### Executive Summary Based on industry research and Syndarix's existing architecture, we recommend a **checkpoint-based approval system** with the following key components: ### Key Recommendations 1. **Queue-Based Approval Pattern** - Single queue with priority lanes (CRITICAL, MILESTONE, ROUTINE) aligned with Syndarix's three autonomy levels (FULL_CONTROL, MILESTONE, AUTONOMOUS) 2. **Confidence-Aware Routing** - AI decisions with confidence below 85% automatically trigger human review regardless of autonomy level 3. **Batch Approval Support** - Efficiency feature for FULL_CONTROL mode users to approve multiple low-risk, routine decisions at once 4. **SSE-Based Notifications** - Leverage existing real-time infrastructure (SPIKE-003) for approval alerts 5. **Mobile-First Design** - One-touch approve/reject with push notifications for urgent decisions 6. **Flexible Timeout & Escalation** - Configurable per project with auto-escalation paths ### Database Schema Highlights - `ApprovalRequest` - Core entity for approval checkpoints - `ApprovalAuditEvent` - Immutable audit trail for compliance - `DelegationRule` - Flexible delegation authority - `EscalationPolicy` - Project-level timeout configuration ### Approval Categories | Category | Use Case | Default Timeout | |----------|----------|-----------------| | CRITICAL | Budget, production deploys | 4 hours | | MILESTONE | Sprint boundaries, architecture | 24 hours | | ROUTINE | PRs, bug fixes | 48 hours | | UNCERTAINTY | Low confidence AI decisions | 12 hours | | EXPERTISE | Agent requests human knowledge | 24 hours | ### Implementation Roadmap - **Phase 1** (Week 1-2): Database schema, core service, API endpoints - **Phase 2** (Week 3-4): Workflow integration (sprints, PRs, deploys) - **Phase 3** (Week 5-6): UI/UX implementation, notifications - **Phase 4** (Week 7-8): Advanced features (escalation, delegation, audit) ### Key Research Sources - [Human-in-the-Loop for AI Agents: Best Practices](https://www.permit.io/blog/human-in-the-loop-for-ai-agents-best-practices-frameworks-use-cases-and-demo) - [Complex Approvals - UXPin Design Guide](https://www.uxpin.com/studio/blog/complex-approvals-app-design/) - [Bulk Approval UX Case Study](https://sreeja-ux-ui-portfolio.webflow.io/projects/bulk-approval) - [Explainable AI for Transparent Agent Decisions](https://www.rapidinnovation.io/post/for-developers-implementing-explainable-ai-for-transparent-agent-decisions) ### Next Steps 1. Review the full spike document for detailed schema, code examples, and UI mockups 2. Create implementation tasks based on the 8-week roadmap 3. Prioritize integration with existing autonomy level configuration (FR-203) --- *Generated by Claude Code - SPIKE-012 Research*
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
agents
Agent orchestration
 architecture
Architectural decisions
 backend
Backend work
 blocked
Blocked by dependency
 database
Database/migrations
 design
UI/UX design work
 devops
DevOps/Infrastructure work
 epic
Epic/parent issue
 frontend
Frontend work
 infrastructure
Infrastructure / DevOps
 mcp
MCP related
 phase-0
Phase 0: Foundation
 phase-1
Phase 1: Core Platform
 phase-2
Phase 2: MCP Integration
 priority:high
High priority
 spike
Architecture spike / research task
No Label
Milestone
No items
No Milestone
Assignees
Clear assignees
cardosofelipe
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: cardosofelipe/syndarix#12
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?