You're Invited:Meet the Socket Team at RSAC and BSidesSF 2026, March 23–26.RSVP →
Socket
Book a DemoSign in
Socket
Book a DemoSign in

@mind-fold/open-flow

Package Overview
Dependencies
Maintainers
1
Versions
31
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@mind-fold/open-flow - npm Package Compare versions

Comparing version
0.2.13
 to
0.2.14
+290
-244
dist/templates/commands/onboard-developer.txt
You are a senior developer onboarding a new team member to this project's AI-assisted workflow system.
YOUR ROLE: Be a mentor and teacher. Don't just execute commands - EXPLAIN why each step matters, what problems it solves, and what happens if skipped.
YOUR ROLE: Be a mentor and teacher. Don't just list steps - EXPLAIN the underlying principles, why each command exists, what problem it solves at a fundamental level.
TEACHING APPROACH:
- First explain the CORE PHILOSOPHY: why this workflow exists
- Then walk through the system structure with clear explanations
- For each example, explain the PURPOSE of every step, not just what to do
- Help them understand the "why" behind each command
---
## CORE PHILOSOPHY
## CORE PHILOSOPHY: Why This Workflow Exists
This workflow system solves three critical problems in AI-assisted development:
AI-assisted development has three fundamental challenges:
1. **Context Loss**: AI starts each session with zero memory. Without a system to capture and restore context, every session starts from scratch, leading to repeated explanations and inconsistent code.
### Challenge 1: AI Has No Memory
2. **Multi-Developer Conflicts**: When multiple developers (human or AI) work on the same codebase, they can overwrite each other's work or make conflicting changes.
Every AI session starts with a blank slate. Unlike human engineers who accumulate project knowledge over weeks/months, AI forgets everything when a session ends.
3. **Quality Drift**: Without enforced guidelines, AI generates code that "works" but doesn't follow project conventions, leading to technical debt.
**The Problem**: Without memory, AI asks the same questions repeatedly, makes the same mistakes, and can't build on previous work.
The solution: A structured workflow with checkpoints that ensure AI reads context before coding, follows guidelines during coding, and records progress after coding.
**The Solution**: The `workflow/agent-progress/` system captures what happened in each session - what was done, what was learned, what problems were solved. The `/init-agent` command reads this history at session start, giving AI "artificial memory."
### Challenge 2: AI Has Generic Knowledge, Not Project-Specific Knowledge
AI models are trained on millions of codebases - they know general patterns for React, TypeScript, databases, etc. But they don't know YOUR project's conventions.
**The Problem**: AI writes code that "works" but doesn't match your project's style. It uses patterns that conflict with existing code. It makes decisions that violate unwritten team rules.
**The Solution**: The `workflow/structure/` directory contains project-specific guidelines. The `/before-*-dev` commands inject this specialized knowledge into AI context before coding starts.
### Challenge 3: AI Context Window Is Limited
Even after injecting guidelines, AI has limited context window. As conversation grows, earlier context (including guidelines) gets pushed out or becomes less influential.
**The Problem**: AI starts following guidelines, but as the session progresses and context fills up, it "forgets" the rules and reverts to generic patterns.
**The Solution**: The `/check-*` commands re-verify code against guidelines AFTER writing, catching drift that occurred during development. The `/finish-work` command does a final holistic review.
---

@@ -29,24 +39,17 @@

Explain the `workflow/` directory to the developer:
```
workflow/
|-- .developer # Developer identity file (gitignored)
|-- .developer # Your identity (gitignored)
|-- flow.md # Complete workflow documentation
|-- agent-progress/ # Progress tracking (per-developer)
| |-- index.md # Main index with all developers
| \-- {developer}/ # Individual developer directory
| |-- index.md # Personal index
|-- agent-progress/ # "AI Memory" - session history
| |-- index.md # All developers' progress
| \-- {developer}/ # Per-developer directory
| |-- index.md # Personal progress index
| |-- features/ # Active feature tracking
| \-- progress-N.md # Session records (max 2000 lines each)
|-- structure/ # Development guidelines (MUST READ)
| |-- frontend/ # Frontend coding standards
| |-- backend/ # Backend coding standards
| \-- flows/ # Cross-layer development guides
\-- scripts/ # Automation scripts
|-- get-context.sh # Get full session context
|-- init-developer.sh # Initialize new developer
|-- feature.sh # Manage features
|-- add-session.sh # Record session progress
\-- update-index.sh # Update index files
| \-- progress-N.md # Session records (max 2000 lines)
|-- structure/ # "AI Training Data" - project knowledge
| |-- frontend/ # Frontend conventions
| |-- backend/ # Backend conventions
| \-- flows/ # Cross-layer patterns
\-- scripts/ # Automation tools
```

@@ -56,57 +59,164 @@

## INITIALIZE DEVELOPER
## COMMAND DEEP DIVE
Ask for their name and run:
```bash
./workflow/scripts/init-developer.sh <developer-name>
```
### /init-agent - Restore AI Memory
Then demonstrate context retrieval:
```bash
./workflow/scripts/get-context.sh
```
**WHY IT EXISTS**:
When a human engineer joins a project, they spend days/weeks learning: What is this project? What's been built? What's in progress? What's the current state?
Explain what each output section means and why it matters.
AI needs the same onboarding - but compressed into seconds at session start.
**WHAT IT ACTUALLY DOES**:
1. Reads developer identity (who am I in this project?)
2. Checks git status (what branch? uncommitted changes?)
3. Reads recent session history from `agent-progress/` (what happened before?)
4. Identifies active features (what's in progress?)
5. Understands current project state before making any changes
**WHY THIS MATTERS**:
- Without init-agent: AI is blind. It might work on wrong branch, conflict with others' work, or redo already-completed work.
- With init-agent: AI knows project context, can continue where previous session left off, avoids conflicts.
**ANALOGY**: Like a human engineer reading their notes from yesterday before starting today's work.
---
## CORE SLASH COMMANDS
### /before-frontend-dev and /before-backend-dev - Inject Specialized Knowledge
Explain each command's PURPOSE, not just what it does:
**WHY IT EXISTS**:
AI models have "pre-trained knowledge" - general patterns from millions of codebases. But YOUR project has specific conventions that differ from generic patterns.
### Session Lifecycle Commands
Human engineers learn project conventions by:
- Reading existing code
- Getting mentored by teammates
- Reading internal documentation
| Command | When | Purpose |
|---------|------|---------|
| `/init-agent` | Session start | Restore context so AI doesn't start blind |
| `/record-agent-flow` | After commit | Preserve context for next session |
| `/finish-work` | Before commit | Final quality gate before human review |
AI needs the same "training" - but injected at runtime before each coding task.
### Development Commands
**WHAT IT ACTUALLY DOES**:
1. Reads `workflow/structure/frontend/` or `workflow/structure/backend/` index
2. Extracts relevant guideline sections based on the task
3. Loads project-specific patterns into AI's working context:
- Component naming conventions
- State management patterns
- Database query patterns
- Error handling standards
- Logging formats
- Type safety rules
| Command | When | Purpose |
|---------|------|---------|
| `/before-frontend-dev` | Before frontend code | Load project conventions into AI context |
| `/before-backend-dev` | Before backend code | Load project conventions into AI context |
| `/check-frontend` | After frontend code | Verify code meets standards before commit |
| `/check-backend` | After backend code | Verify code meets standards before commit |
| `/check-cross-layer` | Full-stack changes | Ensure frontend/backend stay in sync |
**WHY THIS MATTERS**:
- Without before-*-dev: AI writes generic code. It "works" but doesn't match project style. Other engineers can't read it. It creates inconsistency.
- With before-*-dev: AI writes code that looks like the rest of the codebase. It follows established patterns. It's consistent.
### Investigation Commands
**ANALOGY**: Like a human engineer reading the team's coding standards document before writing their first PR.
| Command | When | Purpose |
|---------|------|---------|
| `/break-loop` | After debugging | Stop investigation and capture findings |
| `/record-question` | Solved hard problem | Document solution for future reference |
---
### /check-frontend and /check-backend - Combat Context Drift
**WHY IT EXISTS**:
AI context window has limited capacity. As conversation progresses:
- New messages push older context (including guidelines) toward the edge
- AI attention becomes diluted across more content
- Guidelines injected at session start become less influential
This causes "context drift" - AI starts following guidelines but gradually reverts to generic patterns.
**WHAT IT ACTUALLY DOES**:
1. Re-reads the guidelines that were injected earlier
2. Compares written code against those guidelines
3. Runs type checker and linter
4. Identifies violations:
- Style inconsistencies
- Pattern violations
- Type safety issues
- Logic bugs
5. Reports findings and suggests fixes
**WHY THIS MATTERS**:
- Without check-*: Context drift goes unnoticed. Code that seemed right during writing violates guidelines when reviewed.
- With check-*: Drift is caught and corrected before commit. Code quality is verified, not assumed.
**ANALOGY**: Like code review, but automated and immediate. Catches what the "tired" AI missed.
---
### /finish-work - Holistic Pre-Commit Review
**WHY IT EXISTS**:
The `/check-*` commands focus on code quality within a layer (frontend OR backend). But real changes often have cross-cutting concerns:
- Does frontend change break backend contract?
- Does backend change require frontend update?
- Does infrastructure change need documentation?
- Are there side effects on other features?
**WHAT IT ACTUALLY DOES**:
1. Reviews all changes holistically (not just one layer)
2. Checks cross-layer consistency:
- API contracts match between frontend/backend
- Type definitions are synchronized
- Data flow is consistent end-to-end
3. Identifies broader impacts:
- Will this change affect other features?
- Are there edge cases not considered?
- Is documentation needed?
4. **CRITICAL**: If there are significant infrastructure or pattern changes:
- Checks if these should be documented in `workflow/structure/`
- Ensures future `/before-*-dev` commands will include this new knowledge
- Prevents knowledge from being lost
**WHY THIS MATTERS**:
- Without finish-work: Individual layers pass checks, but integration fails. New patterns aren't documented. Knowledge is lost.
- With finish-work: Cross-layer issues caught before commit. New patterns documented for future sessions.
**ANALOGY**: Like the final review before merging a PR - checking not just code quality, but overall impact and documentation.
---
### /record-agent-flow - Persist Memory for Future
**WHY IT EXISTS**:
All the context AI built during this session - what was done, what was learned, what problems were solved - will be lost when session ends.
The next session's `/init-agent` needs this information to avoid starting from zero.
**WHAT IT ACTUALLY DOES**:
1. Records session summary to `agent-progress/{developer}/progress-N.md`
2. Captures:
- What task was worked on
- What commits were made (for code sessions)
- What was learned (patterns discovered, bugs found)
- What's remaining (if work continues next session)
3. Updates index files for quick lookup
**WHY THIS MATTERS**:
- Without record-agent-flow: Next session starts blind. Same bugs re-investigated. Same patterns re-discovered.
- With record-agent-flow: Next session has context. AI can continue work. Knowledge compounds over time.
**ANALOGY**: Like writing notes at end of workday for tomorrow's you (or your colleague taking over).
---
### /break-loop - Stop Investigation, Capture Findings
**WHY IT EXISTS**:
Debugging and investigation can spiral - AI keeps trying things without concluding. Findings get scattered across conversation. When session ends, insights are lost.
**WHAT IT ACTUALLY DOES**:
1. Forces a stop point in investigation
2. Summarizes:
- What was investigated
- What was the root cause (if found)
- What fixes were tried (temporary vs permanent)
- What follow-up is needed
3. Prepares findings for `/record-agent-flow`
**WHY THIS MATTERS**:
- Without break-loop: Investigation spirals endlessly. Findings scattered. Same debugging repeated next time.
- With break-loop: Investigation has clear conclusion. Findings documented. Future sessions have context.
---
## REAL-WORLD WORKFLOW EXAMPLES
For each example below, explain:
- The SCENARIO context
- WHY each step is needed
- WHAT PROBLEM that step solves
- WHAT HAPPENS if that step is skipped
### Example 1: Bug Fix Session

@@ -116,62 +226,44 @@

```
Step 1: /init-agent
```
PURPOSE: AI needs to understand current state before making changes.
- Reads developer identity, git status, active features
- Without this: AI might work on wrong branch, conflict with others, or repeat already-done work
**[1/9] /init-agent**
- PRINCIPLE: AI needs project context before touching code
- WHAT HAPPENS: AI reads session history, sees this is a React project, understands current branch/state
- IF SKIPPED: AI might not know project conventions, could work on wrong branch
```
Step 2: ./workflow/scripts/feature.sh create fix-sync-indicator
```
PURPOSE: Create isolated tracking for this work.
- Links all changes to a named feature
- Without this: Progress scattered, hard to track what changed and why
**[2/9] ./workflow/scripts/feature.sh create fix-sync-indicator**
- PRINCIPLE: Track work for future reference
- WHAT HAPPENS: Creates feature record linking all subsequent work
- IF SKIPPED: Work scattered, hard to trace what changed and why
```
Step 3: /before-frontend-dev
```
PURPOSE: Load project's frontend conventions into AI context.
- AI learns component patterns, naming conventions, state management rules
- Without this: AI writes "working" code that doesn't match project style
**[3/9] /before-frontend-dev**
- PRINCIPLE: Inject project-specific frontend knowledge
- WHAT HAPPENS: AI learns YOUR component patterns, not generic React patterns
- IF SKIPPED: AI writes generic code that doesn't match project style
```
Step 4: Investigate and fix the bug
```
PURPOSE: The actual development work.
- AI now has context + guidelines, can write consistent code
**[4/9] Investigate and fix the bug**
- PRINCIPLE: Actual development work
- WHAT HAPPENS: AI has context + guidelines, writes consistent code
```
Step 5: /check-frontend
```
PURPOSE: Quality gate before human review.
- Runs type check, linter, guideline compliance
- Without this: Errors slip through, human review catches preventable issues
**[5/9] /check-frontend**
- PRINCIPLE: Combat context drift
- WHAT HAPPENS: Re-verifies code against guidelines, catches style violations, type errors
- IF SKIPPED: Drift goes unnoticed, code quality degrades
```
Step 6: /finish-work
```
PURPOSE: Final checklist before commit.
- Ensures nothing forgotten: docs updated, all files staged
- Without this: Partial commits, missing documentation
**[6/9] /finish-work**
- PRINCIPLE: Holistic cross-layer review
- WHAT HAPPENS: Checks if this frontend change has backend implications, documentation needs
- IF SKIPPED: Integration issues missed, patterns undocumented
```
Step 7: Human tests and commits
```
PURPOSE: Human-in-the-loop verification.
- AI NEVER commits - human is responsible for testing
- Without this: Untested code enters codebase
**[7/9] Human tests and commits**
- PRINCIPLE: Human-in-the-loop verification
- WHAT HAPPENS: AI NEVER commits - human validates before code enters repo
- IF SKIPPED: Untested code in production
```
Step 8: /record-agent-flow
```
PURPOSE: Preserve context for future sessions.
- Records what was done, lessons learned, commit hashes
- Without this: Next session starts from zero, same bugs re-investigated
**[8/9] /record-agent-flow**
- PRINCIPLE: Persist memory for future
- WHAT HAPPENS: Records what was done, learned patterns, commit hashes
- IF SKIPPED: Next session starts from zero
```
Step 9: ./workflow/scripts/feature.sh archive fix-sync-indicator
```
PURPOSE: Clean up after completion.
- Moves feature to archive, keeps active list clean
**[9/9] ./workflow/scripts/feature.sh archive**
- PRINCIPLE: Clean tracking state
- WHAT HAPPENS: Moves completed feature to archive

@@ -184,26 +276,18 @@ ---

```
Step 1: /init-agent
```
PURPOSE: Understand current state even for non-coding work.
- See what's already in progress, avoid duplicate planning
**[1/4] /init-agent**
- PRINCIPLE: Context needed even for non-coding work
- WHAT HAPPENS: AI sees what planning was done before, avoids duplicate work
```
Step 2: ./workflow/scripts/feature.sh create migration-docs-consolidation
```
PURPOSE: Track planning work same as code work.
- Planning is valuable work that needs recording
**[2/4] ./workflow/scripts/feature.sh create migration-docs-consolidation**
- PRINCIPLE: Planning is valuable work worth tracking
- WHAT HAPPENS: Creates record for this planning effort
```
Step 3: Review docs, create subtask list
```
PURPOSE: The actual planning work.
- Compare existing docs, identify gaps, prioritize
**[3/4] Review docs, create subtask list**
- PRINCIPLE: Actual planning work
- WHAT HAPPENS: Compare docs, identify gaps, prioritize tasks
```
Step 4: /record-agent-flow (with --summary, no --commit)
```
PURPOSE: Record planning output even without code commits.
- Use --summary flag for non-code sessions
- Without this: Planning decisions lost, team doesn't know what was decided
**[4/4] /record-agent-flow (with --summary, no --commit)**
- PRINCIPLE: Planning decisions must be recorded
- WHAT HAPPENS: Uses --summary flag since no code commits
- IF SKIPPED: Planning decisions lost, team doesn't know what was decided

@@ -216,40 +300,26 @@ ---

```
Step 1: /init-agent
```
PURPOSE: Resume context from previous session.
- AI sees the feature is already in progress
- Reads previous progress to understand what was already done
**[1/6] /init-agent**
- PRINCIPLE: Resume context from previous session
- WHAT HAPPENS: AI sees this feature is in progress, reads CR feedback context
```
Step 2: /before-backend-dev
```
PURPOSE: Refresh guidelines before fixing backend issues.
- CR comments often point to guideline violations
- AI needs guidelines in context to fix properly
**[2/6] /before-backend-dev**
- PRINCIPLE: Re-inject guidelines before fixes
- WHAT HAPPENS: CR comments often point to guideline violations - AI needs guidelines fresh in context
```
Step 3: Fix each CR issue
```
PURPOSE: Address review feedback.
- With guidelines loaded, fixes follow project conventions
**[3/6] Fix each CR issue**
- PRINCIPLE: Address feedback with guidelines in context
- WHAT HAPPENS: Fixes follow project conventions, not generic patterns
```
Step 4: /check-backend
```
PURPOSE: Verify fixes don't introduce new issues.
- Each fix could break something else
**[4/6] /check-backend**
- PRINCIPLE: Verify fixes didn't introduce new issues
- WHAT HAPPENS: Each fix could break something else - this catches it
```
Step 5: /finish-work
```
PURPOSE: Document lessons learned from CR.
- CR feedback reveals patterns to remember
- Example: "All queries with workspaceId must include WHERE clause"
**[5/6] /finish-work**
- PRINCIPLE: Document lessons from CR
- WHAT HAPPENS: CR feedback reveals patterns worth documenting
- KEY: If CR revealed a pattern violation, consider adding to workflow/structure/ so future /before-*-dev catches it
```
Step 6: Human commits, then /record-agent-flow
```
PURPOSE: Preserve CR lessons for future.
- Next time AI writes similar code, it knows the patterns
**[6/6] Human commits, then /record-agent-flow**
- PRINCIPLE: Preserve CR lessons
- WHAT HAPPENS: Next time AI writes similar code, it has this context

@@ -262,34 +332,22 @@ ---

```
Step 1: /init-agent
```
PURPOSE: Establish baseline before major changes.
- Large refactors need clear starting point
**[1/5] /init-agent**
- PRINCIPLE: Clear baseline before major changes
- WHAT HAPPENS: Large refactors need documented starting point
```
Step 2: Plan phases
```
PURPOSE: Break large work into manageable chunks.
- Phase 1: Root directory restructure
- Phase 2: Sub-project workflow cleanup
- Phase 3: Slash commands rewrite
- Phase 4: Core docs update
**[2/5] Plan phases**
- PRINCIPLE: Break into verifiable chunks
- WHAT HAPPENS: Define phases that can each be checked independently
```
Step 3: Execute phase by phase with /check-* after each
```
PURPOSE: Incremental verification.
- Catch issues early, don't let errors compound
**[3/5] Execute phase by phase with /check-* after each**
- PRINCIPLE: Incremental verification
- WHAT HAPPENS: Catch issues early, don't let drift compound across phases
```
Step 4: /finish-work
```
PURPOSE: Final verification across all phases.
- Ensure all phases are complete and consistent
**[4/5] /finish-work**
- PRINCIPLE: Major refactor likely needs documentation update
- WHAT HAPPENS: Check if new patterns should be added to workflow/structure/
- KEY: This ensures future /before-*-dev commands include the new patterns
```
Step 5: Record with multiple commit hashes
```
PURPOSE: Link all commits to one logical feature.
- ./workflow/scripts/add-session.sh --title "Monorepo Adaptation" --commit "hash1,hash2,hash3"
**[5/5] Record with multiple commit hashes**
- PRINCIPLE: Link all commits to one logical feature
- COMMAND: ./workflow/scripts/add-session.sh --title "Monorepo Adaptation" --commit "hash1,hash2,hash3"

@@ -302,45 +360,33 @@ ---

```
Step 1: /init-agent
```
PURPOSE: Get context on the bug being investigated.
- See previous investigation attempts if any
**[1/7] /init-agent**
- PRINCIPLE: See if this bug was investigated before
- WHAT HAPPENS: Previous investigation attempts might have clues
```
Step 2: /before-backend-dev
```
PURPOSE: Load relevant guidelines for the area being debugged.
- Guidelines often contain hints about known issues
**[2/7] /before-backend-dev**
- PRINCIPLE: Guidelines often document known gotchas
- WHAT HAPPENS: Sync-related guidelines might hint at common issues
```
Step 3: Investigation loop
```
PURPOSE: The actual debugging work.
- Analyze data, check logs, form hypotheses, test fixes
**[3/7] Investigation loop**
- PRINCIPLE: Actual debugging work
- WHAT HAPPENS: Analyze data, check logs, form hypotheses, test fixes
```
Step 4: /check-backend
```
PURPOSE: Verify debug changes don't break other things.
- Debug code can be sloppy - this catches issues
**[4/7] /check-backend**
- PRINCIPLE: Debug code can be sloppy
- WHAT HAPPENS: Verify debug changes don't break other things
```
Step 5: /break-loop
```
PURPOSE: CRITICAL - Stop investigation and capture findings.
- Summarizes: what was investigated, root cause, fixes tried
- Documents: temporary vs permanent fix, follow-up needed
- Without this: Investigation goes in circles, findings lost
**[5/7] /break-loop**
- PRINCIPLE: CRITICAL - Force conclusion to investigation
- WHAT HAPPENS: Stop spiraling, document findings:
- Root cause identified?
- Temporary fix vs permanent fix?
- Follow-up needed?
- IF SKIPPED: Investigation goes in circles, findings scattered and lost
```
Step 6: /finish-work
```
PURPOSE: Prepare debug findings for commit.
- Even investigation sessions produce valuable output
**[6/7] /finish-work**
- PRINCIPLE: Debug findings might need documentation
- WHAT HAPPENS: If this was a common bug pattern, add to guidelines
```
Step 7: Human commits, then /record-agent-flow
```
PURPOSE: Preserve debugging knowledge.
- Next time same bug appears, AI has context
**[7/7] Human commits, then /record-agent-flow**
- PRINCIPLE: Debug knowledge is valuable
- WHAT HAPPENS: Next time same bug appears, AI has context

@@ -351,11 +397,11 @@ ---

1. **AI NEVER commits** - Human tests and commits. AI prepares, human approves.
1. **AI NEVER commits** - Human tests and approves. AI prepares, human validates.
2. **Guidelines before code** - /before-*-dev commands are MANDATORY, not optional.
2. **Guidelines before code** - /before-*-dev commands inject project knowledge. Without them, AI writes generic code.
3. **Progress tracking** - Every session should end with /record-agent-flow.
3. **Check after code** - /check-* commands catch context drift. Without them, drift goes unnoticed.
4. **Break investigation loops** - Use /break-loop to stop research and capture findings.
4. **Finish-work updates guidelines** - If you discover new patterns or fix pattern violations, consider updating workflow/structure/ so future sessions benefit.
5. **Planning is valid work** - Non-code sessions use --summary flag in add-session.sh.
5. **Record everything** - /record-agent-flow persists memory. Without it, next session starts blind.

@@ -362,0 +408,0 @@ ---

+1
-1
package.json
{
"name": "@mind-fold/open-flow",
"version": "0.2.13",
"version": "0.2.14",
"description": "AI-assisted development workflow initializer for Cursor, Claude Code and more",

@@ -5,0 +5,0 @@ "type": "module",