skills.rest
marcocpt
marcocptCOMMUNITY
Explore all skills by this author →
GitHub

dd-shared-state

Persists workflow state to JSON files in git directories for session recovery.

Updated Jun 11, 2026
Search Tags:#workflow automation#session management#git worktree#state persistence#context recovery#json state file#concurrency check
One-click install
npx skills add https://github.com/marcocpt/trae_skills --skill dd-shared-state-marcocpt
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: dd-shared-state
Source: https://github.com/marcocpt/trae_skills/tree/main/dd-shared-state
Command: npx skills add https://github.com/marcocpt/trae_skills --skill dd-shared-state-marcocpt

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When an AI session's context is compressed or lost mid-workflow, critical state like worktree paths, base branches, current branches, and step numbers can be forgotten. This Skill solves that by persisting workflow state to per-worktree JSON files, enabling reliable context recovery and parallel multi-session development. ## Core Features & Use Cases - State File Persistence: Writes workflow state (worktree path, base branch, current step, timestamps) to a JSON file inside the git directory, invisible to git status. - Parameterized Workflows: Supports both bug-fix and feature-development workflows via WORKFLOW_TYPE and BRANCH_FIELD parameters. - Recovery & Concurrency Control: Provides a step-by-step recovery procedure when state files are missing, plus concurrency checks that block multiple workflows on the same worktree. - Use Case: After a long bug-fix session gets compacted, the agent reads bug-fix-state.json from the worktree's git dir, restores the branch and step number, and resumes exactly where it left off instead of restarting. ## Quick Start Ask the agent to restore my current workflow context using the shared state file before continuing the bug-fix workflow.

Frequently Asked Questions about dd-shared-state

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I recover workflow context after session compaction?▼

Read the state file from `$(git rev-parse --git-dir)/<workflow-type>-state.json` and load fields like worktree_path, base_branch, and current_step into the environment. Then cd into the worktree path and resume from the recorded step.

Where should workflow state files be stored in git worktrees?▼

Store state files inside the git directory returned by `git rev-parse --git-dir`. This location is private to each worktree and invisible to `git status`, so every worktree maintains an independent state file.

What happens if the state file is missing during recovery?▼

Do not restart from step zero by default. Check whether the current directory is a worktree, inspect the branch name pattern, and compare commits against the base branch to infer whether the workflow is mid-TDD or mid-merge before deciding.

Can multiple workflows run on the same git worktree?▼

No. Before starting a new workflow, the concurrency check scans the git dir for existing bug-fix-state.json or feature-development-state.json files and aborts if any active workflow is detected on that worktree.

When should the workflow state file be deleted?▼

Delete the state file only after `git merge --no-ff` succeeds, never before merging. Before merging, set `merge_in_progress` to true so an interrupted merge can be detected and recovered.

Related Skills

Explore More Software Engineering Skills→
ShiienShiien
7

code-branch

Create a dedicated git branch or worktree for isolated coding tasks.

Community
Intermediate
whinchmanwhinchman

coder

Implements features and fixes with test-driven development in isolated git worktrees.

Community
Advanced
KorytoKoryto
3

closeout

Update summary, project progress, session state, and session logs during the Summary phase.

Community
Intermediate
CAPHTECHCAPHTECH
1

lde-grounding-api

Compress long-term task history into structured Session Notes and Progress Summaries.

Official
Basic