Sync ALL increment specifications to living docs structure by default. Creates FS-XXX folders for each increment. Use with increment ID to sync single increment.
Syncs increment specifications to living docs structure. Use without arguments to sync ALL increments, or specify an increment ID to sync a single one.
/plugin marketplace add anton-abyzov/specweave/plugin install sw@specweaveDEFAULT BEHAVIOR: Syncs ALL increments to living docs (not just one!)
Arguments provided: $ARGUMENTS
Parse the input to determine sync mode:
| Input | Mode | Action |
|---|---|---|
/sw:sync-specs | ALL (default) | Sync ALL increments |
/sw:sync-specs --all | ALL (explicit) | Sync ALL increments |
/sw:sync-specs 0106 | SINGLE | Sync only increment 0106 |
/sw:sync-specs 0106 --dry-run | SINGLE + DRY | Preview sync for 0106 |
/sw:sync-specs --dry-run | ALL + DRY | Preview sync for ALL |
CRITICAL: No increment ID = sync ALL increments (this is the DEFAULT!)
This is the DEFAULT when no increment ID is provided!
# List ALL syncable increments (with spec.md)
ls -1 .specweave/increments/ | grep -E '^[0-9]{4}E?-' | sort
Execute sync for EACH increment:
š Syncing ALL increments to living docs...
Found {N} increments with spec.md files.
For each increment, call the sync logic:
import { LivingDocsSync } from './src/core/living-docs/living-docs-sync.js';
const sync = new LivingDocsSync(projectRoot);
// Get all increment folders
const incrementsDir = '.specweave/increments';
const entries = fs.readdirSync(incrementsDir);
const increments = entries.filter(e => /^\d{4}E?-/.test(e));
let successCount = 0;
let failCount = 0;
const results = [];
for (const incrementId of increments.sort()) {
// Check if spec.md exists
const specPath = path.join(incrementsDir, incrementId, 'spec.md');
if (!fs.existsSync(specPath)) {
console.log(` ā ļø Skipping ${incrementId} (no spec.md)`);
continue;
}
try {
const result = await sync.syncIncrement(incrementId, { dryRun, force });
if (result.success) {
successCount++;
results.push({ id: incrementId, featureId: result.featureId, status: 'ā
' });
} else {
failCount++;
results.push({ id: incrementId, featureId: '', status: 'ā', error: result.errors[0] });
}
} catch (error) {
failCount++;
results.push({ id: incrementId, featureId: '', status: 'ā', error: error.message });
}
}
Output summary table:
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā
BULK SYNC COMPLETE
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
| Increment | Feature ID | Status |
|-----------|------------|--------|
| 0093-ado-permission-profile-fixes | FS-093 | ā
|
| 0094-unit-test-alignment | FS-094 | ā
|
| 0095-per-project-epic-hierarchy | FS-095 | ā
|
| ... | ... | ... |
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
š SUMMARY
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
Total increments: {N}
ā
Succeeded: {successCount}
ā Failed: {failCount}
āļø Skipped: {skippedCount} (no spec.md)
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
Only when a specific increment ID is provided:
šÆ Target increment: {increment_id}
š Increment path: .specweave/increments/{increment_id}
š Mode: Single increment sync
Execute single sync:
const result = await sync.syncIncrement(incrementId, { dryRun, force });
Output:
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā
SINGLE INCREMENT SYNC COMPLETE
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
Increment: {increment_id}
Feature ID: FS-{XXX} (derived from increment number)
Project: {project}
Files created:
⢠{project}/FS-{XXX}/FEATURE.md
⢠{project}/FS-{XXX}/us-001-*.md
⢠{project}/FS-{XXX}/us-002-*.md
...
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
After sync, compare increments vs specs:
# Get all increment numbers
INCREMENT_NUMS=$(ls -1 .specweave/increments/ | grep -E '^[0-9]{4}E?-' | sed 's/^\([0-9]*E\?\).*/\1/')
# Get all FS-XXX folders in specs
SPEC_NUMS=$(ls -1 .specweave/docs/internal/specs/*/FS-* 2>/dev/null | grep -oE 'FS-[0-9]+E?' | sed 's/FS-//')
# Find missing (increments without corresponding FS-XXX)
echo "Checking for gaps..."
Report gaps (increments without corresponding specs):
š GAP ANALYSIS
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
{if gaps found}
ā ļø Found {N} increments without corresponding specs:
⢠0106-ci-health-improvements ā FS-106 missing
⢠0113-enhanced-living-docs-architecture ā FS-113 missing
These were synced in this run.
{else}
ā
All increments have corresponding spec folders!
{/if}
CRITICAL: Feature ID is ALWAYS derived from increment number:
| Increment ID | Feature ID |
|---|---|
| 0002-user-authentication | FS-002 |
| 0040-some-feature | FS-040 |
| 0106-ci-health | FS-106 |
| 0111E-dora-metrics-fix | FS-111E |
Rules:
XXXX-name ā Feature FS-XXX (3-digit minimum)XXXXE-name (external) ā Feature FS-XXXEPreview what would be synced without making changes:
/sw:sync-specs --dry-run # Preview ALL
/sw:sync-specs 0106 --dry-run # Preview single
Overwrite existing files without prompting:
/sw:sync-specs --force # Force ALL
/sw:sync-specs 0106 --force # Force single
User: /sw:sync-specs
Output:
š Syncing ALL increments to living docs...
Found 25 increments with spec.md files.
| Increment | Feature ID | Status |
|-----------|------------|--------|
| 0093-ado-permission-profile-fixes | FS-093 | ā
|
| 0094-unit-test-alignment | FS-094 | ā
|
| 0095-per-project-epic-hierarchy | FS-095 | ā
|
| 0096-ado-import-fixes | FS-096 | ā
|
| 0097-umbrella-module-detection | FS-097 | ā
|
| ... | ... | ... |
| 0116-livingspec-universal-standard | FS-116 | ā
|
š SUMMARY: 25 succeeded, 0 failed
User: /sw:sync-specs 0106
Output:
šÆ Target increment: 0106-ci-health-improvements
š Increment path: .specweave/increments/0106-ci-health-improvements
š Mode: Single increment sync
ā
Synced 0106-ci-health-improvements ā FS-106
Created: specweave/FS-106/FEATURE.md
Created: specweave/FS-106/us-001-*.md
User: /sw:sync-specs --dry-run
Output:
š DRY RUN MODE - No files will be modified
Would sync 25 increments:
⢠0093 ā FS-093 (exists, would update)
⢠0094 ā FS-094 (exists, would update)
⢠0106 ā FS-106 (NEW - would create)
⢠0113 ā FS-113 (NEW - would create)
...
No changes made (dry run mode)
ā Error: No increments found in .specweave/increments/
Create an increment first:
/sw:increment "feature name"
ā Error: Increment '0999' not found
Available increments:
0093-ado-permission-profile-fixes
0094-unit-test-alignment
...
Usage: /sw:sync-specs [increment_id]
ā ļø Skipping 0107-incomplete-feature (no spec.md)
Increment must have a spec.md file to sync.
project: from spec.md YAML frontmatterā
Use /sw:sync-specs (no args) when:
ā
Use /sw:sync-specs <id> when:
Execute this command now. Default = sync ALL increments.