Skip to content

Latest commit

 

History

History
418 lines (300 loc) · 8.44 KB

manual-workflows-guide.md

File metadata and controls

418 lines (300 loc) · 8.44 KB

Manual Workflows Guide

Complete guide for manual workflows when automation is not available

Overview

This guide provides step-by-step instructions for common workflows when using scene-capability-engine without automation (watch mode or agent hooks). These workflows are designed to be efficient and easy to follow.

When to use manual workflows:

  • When automation is not set up
  • When working in environments without watch mode support
  • When you prefer manual control over automation
  • For one-off tasks or testing

Table of Contents

  1. Task Sync Workflow
  2. Context Export Workflow
  3. Prompt Generation Workflow
  4. Workflow Checklists

Task Sync Workflow

Purpose

Keep your workspace synchronized with task progress across multiple users or tools.

Time Estimate

  • Initial sync: 2-3 minutes
  • Subsequent syncs: 30-60 seconds

Prerequisites

  • Project adopted with scene-capability-engine
  • Active spec with tasks.md file
  • Write access to .sce/specs/ directory

Step-by-Step Instructions

1. Check Current Status

sce status

What to look for:

  • Current spec name
  • Number of tasks (total, completed, in progress)
  • Last sync timestamp

Time: ~5 seconds

2. Review Task Changes

Open your spec's tasks.md file and review:

  • Tasks you've completed (mark with [x])
  • Tasks you're working on (mark with [-])
  • Tasks you've queued (mark with [~])

Example:

- [x] 1.1 Completed task
- [-] 1.2 In progress task
- [~] 1.3 Queued task
- [ ] 1.4 Not started task

Time: ~30-60 seconds

3. Sync Workspace

sce workspace sync

What this does:

  • Updates workspace metadata
  • Synchronizes task status
  • Detects conflicts
  • Updates timestamps

Time: ~10-15 seconds

4. Verify Sync

sce status

Verify:

  • Task counts are updated
  • Sync timestamp is current
  • No conflicts reported

Time: ~5 seconds

Best Practices

  1. Sync Frequency

    • Before starting work: Always sync first
    • After completing tasks: Sync immediately
    • During long sessions: Sync every 30-60 minutes

  2. Conflict Resolution

    • If conflicts detected, review both versions
    • Keep the most recent accurate state
    • Document resolution in commit message

  3. Team Coordination

    • Communicate task claims in team chat
    • Use task claiming feature: sce task claim <spec> <task-id>
    • Check for claimed tasks before starting work

Context Export Workflow

Purpose

Export spec context for sharing with AI assistants or team members.

Time Estimate

  • Single spec export: 15-30 seconds
  • With steering rules: 30-45 seconds

Prerequisites

  • Active spec with requirements, design, and tasks
  • Optional: Steering rules configured

Step-by-Step Instructions

1. Identify Spec to Export

sce status

Note the spec name you want to export.

Time: ~5 seconds

2. Export Context

sce context export <spec-name>

Options:

  • --include-steering: Include steering rules
  • --steering-files <files>: Specific steering files (comma-separated)
  • --output <path>: Custom output path

Example:

sce context export my-feature --include-steering --steering-files CORE_PRINCIPLES.md,ENVIRONMENT.md

Time: ~10-20 seconds

3. Locate Export File

The export is saved to:

.sce/specs/<spec-name>/context-export.md

Time: ~5 seconds

4. Use Exported Context

  • Copy content to AI assistant
  • Share with team members
  • Use as documentation reference
  • Include in project handoff

Time: Varies by use case

Best Practices

  1. When to Export

    • Before starting a new task
    • When asking for AI assistance
    • For project documentation
    • During team handoffs

  2. What to Include

    • Always: requirements, design, tasks
    • Usually: core steering rules
    • Sometimes: environment-specific rules
    • Rarely: all steering rules (too verbose)

  3. Export Management

    • Exports are regenerated each time
    • Old exports are overwritten
    • Consider versioning important exports
    • Clean up old exports periodically

Prompt Generation Workflow

Purpose

Generate AI prompts for specific tasks with relevant context.

Time Estimate

  • Single task prompt: 20-30 seconds
  • Batch generation: 1-2 minutes per 10 tasks

Prerequisites

  • Active spec with tasks
  • Task IDs identified
  • Requirements and design documents complete

Step-by-Step Instructions

1. Identify Task

Review tasks.md and note the task ID:

cat .sce/specs/<spec-name>/tasks.md

Example task ID: 1.2 or 3.1.1

Time: ~10-15 seconds

2. Generate Prompt

sce prompt generate <spec-name> <task-id>

Options:

  • --target <tool>: Target tool (SCE, vscode, cursor, other)
  • --output <path>: Custom output path

Example:

sce prompt generate my-feature 1.2 --target vscode

Time: ~10-15 seconds

3. Locate Generated Prompt

The prompt is saved to:

.sce/specs/<spec-name>/prompts/task-<task-id>.md

Time: ~5 seconds

4. Use Generated Prompt

  • Copy to AI assistant
  • Review for accuracy
  • Customize if needed
  • Execute task based on prompt

Time: Varies by task complexity

Batch Operations

For multiple tasks:

# Generate prompts for all incomplete tasks
for task in 1.1 1.2 1.3; do
  sce prompt generate my-feature $task
done

Time: ~20-30 seconds per task

Best Practices

  1. Prompt Quality

    • Review generated prompts before use
    • Customize for specific context
    • Add tool-specific instructions
    • Include relevant examples

  2. Prompt Organization

    • Keep prompts in spec directory
    • Use consistent naming
    • Version control prompts
    • Clean up after task completion

  3. Optimization Tips

    • Generate prompts in batches
    • Reuse prompts for similar tasks
    • Template common patterns
    • Document customizations

Workflow Checklists

Daily Workflow Checklist

Morning (Start of Work)

  • Sync workspace: sce workspace sync
  • Check status: sce status
  • Review task list
  • Claim tasks you'll work on
  • Export context for active tasks

During Work

  • Update task status as you progress
  • Sync every 30-60 minutes
  • Export context when asking for help
  • Generate prompts for new tasks

End of Day

  • Mark completed tasks
  • Update in-progress tasks
  • Final sync: sce workspace sync
  • Commit changes to version control

Task Completion Checklist

  • Review task requirements
  • Generate task prompt
  • Export context if needed
  • Complete implementation
  • Run tests
  • Update task status to completed
  • Sync workspace
  • Commit changes

Spec Creation Checklist

  • Create spec: sce spec bootstrap --name <name> --non-interactive
  • Write requirements.md
  • Write design.md
  • Generate tasks.md
  • Export initial context
  • Generate prompts for first tasks
  • Sync workspace
  • Begin implementation

Time Estimates Summary

Workflow Time Estimate
Task Sync 30-60 seconds
Context Export 15-45 seconds
Prompt Generation 20-30 seconds
Daily Sync Routine 2-3 minutes
Full Spec Setup 10-15 minutes

Troubleshooting

Common Issues

Issue: Sync conflicts

  • Solution: Review both versions, keep most recent
  • Prevention: Sync more frequently

Issue: Export fails

  • Solution: Check spec exists, files are readable
  • Prevention: Verify spec structure before export

Issue: Prompt generation incomplete

  • Solution: Ensure requirements and design are complete
  • Prevention: Complete docs before generating prompts

Next Steps

  1. Set Up Automation: Consider using watch mode for automatic workflows

    sce watch init
sce watch install auto-sync

  2. Learn More:

  3. Get Help:

Version: 1.0
Last Updated: 2026-01-23
Spec: 05-00-agent-hooks-and-automation