├── handoff-manager ├── docs │ ├── cloud-button.png │ └── index.md ├── .roomodes ├── .clinerules ├── handoffs │ └── 0-system │ │ ├── chat-history │ │ └── README.md │ │ ├── scripts │ │ ├── 2-create-milestone.py │ │ ├── 2-create-milestone.js │ │ └── README.md │ │ └── instructions │ │ ├── 3-milestone-scripts.md │ │ └── prompts │ │ ├── CH-create-handoff.md │ │ ├── CH-create-handoff-with-extraction.md │ │ └── CM-create-milestone.md └── single-script │ └── handoff-installer-readme.md ├── .gitignore ├── handoff-system ├── handoff-publisher │ ├── node_modules │ │ ├── fs-extra │ │ │ ├── lib │ │ │ │ ├── copy │ │ │ │ │ └── index.js │ │ │ │ ├── move │ │ │ │ │ ├── index.js │ │ │ │ │ ├── move-sync.js │ │ │ │ │ └── move.js │ │ │ │ ├── json │ │ │ │ │ ├── jsonfile.js │ │ │ │ │ ├── output-json.js │ │ │ │ │ ├── output-json-sync.js │ │ │ │ │ └── index.js │ │ │ │ ├── path-exists │ │ │ │ │ └── index.js │ │ │ │ ├── mkdirs │ │ │ │ │ ├── index.js │ │ │ │ │ ├── make-dir.js │ │ │ │ │ └── utils.js │ │ │ │ ├── remove │ │ │ │ │ └── index.js │ │ │ │ ├── index.js │ │ │ │ ├── ensure │ │ │ │ │ ├── index.js │ │ │ │ │ ├── symlink-type.js │ │ │ │ │ ├── link.js │ │ │ │ │ ├── file.js │ │ │ │ │ ├── symlink.js │ │ │ │ │ └── symlink-paths.js │ │ │ │ ├── output-file │ │ │ │ │ └── index.js │ │ │ │ ├── util │ │ │ │ │ └── utimes.js │ │ │ │ ├── empty │ │ │ │ │ └── index.js │ │ │ │ └── esm.mjs │ │ │ ├── LICENSE │ │ │ └── package.json │ │ ├── jsonfile │ │ │ ├── utils.js │ │ │ ├── package.json │ │ │ ├── LICENSE │ │ │ └── index.js │ │ ├── graceful-fs │ │ │ ├── clone.js │ │ │ ├── LICENSE │ │ │ ├── package.json │ │ │ └── legacy-streams.js │ │ ├── universalify │ │ │ ├── index.js │ │ │ ├── package.json │ │ │ ├── LICENSE │ │ │ └── README.md │ │ └── .package-lock.json │ ├── package.json │ ├── lib │ │ ├── src │ │ │ ├── src-config.json │ │ │ ├── 4-file-writer.js │ │ │ ├── 5-installer.js │ │ │ └── 2-backup.js │ │ └── src-assembler.js │ ├── package-lock.json │ ├── config │ │ └── publish-config.json │ ├── docs │ │ ├── publish-workflow.md │ │ └── component-sets-specification.md │ └── README.md ├── 1-handoff-custom-mode │ ├── .roomodes │ ├── components │ │ ├── 2-virtual-tools.md │ │ ├── 12-workflow-summary.md │ │ ├── 1-header.md │ │ ├── 11-safety-rules.md │ │ ├── system-prompt-config.json │ │ ├── 3-directory-detection.md │ │ ├── 6-handoff-creation.md │ │ ├── 10-numbering-logic.md │ │ ├── 8-session-restoration.md │ │ ├── 9-conversation-extraction.md │ │ ├── 4-restoration-flowchart.md │ │ ├── 7-milestone-creation.md │ │ └── 5-creation-flowchart.md │ ├── .clinerules │ └── README.md ├── chat-history-template │ └── README.md ├── 2-scripts │ ├── 2-create-milestone.py │ ├── README.md │ └── 2-create-milestone.js ├── README.md ├── 0-instructions │ ├── 3-milestone-scripts.md │ ├── prompts │ │ ├── CH-create-handoff.md │ │ ├── CM-create-milestone.md │ │ └── RS-restore-session.md │ └── 0-intro.md ├── publish-handoff-manager.js └── handoff-installer-readme.md ├── handoffs ├── .clinerules ├── .clinerules-session-restorer ├── 0-instructions │ ├── prompts │ │ ├── CH-create-handoff.md │ │ ├── CM-create-milestone.md │ │ └── RS-restore-session.md │ ├── 3-milestone-scripts.md │ ├── 0-intro.md │ ├── 1-handoff-instructions.md │ └── 2-milestone-instructions.md ├── .clinerules-milestone-manager └── .clinerules-handoff-manager ├── .roomodes ├── .clinerules ├── roomodes-validator └── README.md ├── personal_roo_docs ├── normal │ └── README.md └── technical │ └── README.md ├── roo-ignore └── README.md └── single-script └── handoff-installer-readme.md /handoff-manager/docs/cloud-button.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Michaelzag/RooCode-Tips-Tricks/HEAD/handoff-manager/docs/cloud-button.png -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | ignored/ 2 | /deprecated/ 3 | roo-army/ 4 | roo-army/roo-army-test/ 5 | .obsidian 6 | personal_roo_docs/theoretical/ 7 | .rooignore 8 | roomodes-validator/tests 9 | handoffs-backup -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/copy/index.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const u = require('universalify').fromPromise 4 | module.exports = { 5 | copy: u(require('./copy')), 6 | copySync: require('./copy-sync') 7 | } 8 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/move/index.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const u = require('universalify').fromPromise 4 | module.exports = { 5 | move: u(require('./move')), 6 | moveSync: require('./move-sync') 7 | } 8 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/json/jsonfile.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const jsonFile = require('jsonfile') 4 | 5 | module.exports = { 6 | // jsonfile exports 7 | readJson: jsonFile.readFile, 8 | readJsonSync: jsonFile.readFileSync, 9 | writeJson: jsonFile.writeFile, 10 | writeJsonSync: jsonFile.writeFileSync 11 | } 12 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/path-exists/index.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | const u = require('universalify').fromPromise 3 | const fs = require('../fs') 4 | 5 | function pathExists (path) { 6 | return fs.access(path).then(() => true).catch(() => false) 7 | } 8 | 9 | module.exports = { 10 | pathExists: u(pathExists), 11 | pathExistsSync: fs.existsSync 12 | } 13 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/json/output-json.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const { stringify } = require('jsonfile/utils') 4 | const { outputFile } = require('../output-file') 5 | 6 | async function outputJson (file, data, options = {}) { 7 | const str = stringify(data, options) 8 | 9 | await outputFile(file, str, options) 10 | } 11 | 12 | module.exports = outputJson 13 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/json/output-json-sync.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const { stringify } = require('jsonfile/utils') 4 | const { outputFileSync } = require('../output-file') 5 | 6 | function outputJsonSync (file, data, options) { 7 | const str = stringify(data, options) 8 | 9 | outputFileSync(file, str, options) 10 | } 11 | 12 | module.exports = outputJsonSync 13 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/mkdirs/index.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | const u = require('universalify').fromPromise 3 | const { makeDir: _makeDir, makeDirSync } = require('./make-dir') 4 | const makeDir = u(_makeDir) 5 | 6 | module.exports = { 7 | mkdirs: makeDir, 8 | mkdirsSync: makeDirSync, 9 | // alias 10 | mkdirp: makeDir, 11 | mkdirpSync: makeDirSync, 12 | ensureDir: makeDir, 13 | ensureDirSync: makeDirSync 14 | } 15 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/remove/index.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const fs = require('graceful-fs') 4 | const u = require('universalify').fromCallback 5 | 6 | function remove (path, callback) { 7 | fs.rm(path, { recursive: true, force: true }, callback) 8 | } 9 | 10 | function removeSync (path) { 11 | fs.rmSync(path, { recursive: true, force: true }) 12 | } 13 | 14 | module.exports = { 15 | remove: u(remove), 16 | removeSync 17 | } 18 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/index.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | module.exports = { 4 | // Export promiseified graceful-fs: 5 | ...require('./fs'), 6 | // Export extra methods: 7 | ...require('./copy'), 8 | ...require('./empty'), 9 | ...require('./ensure'), 10 | ...require('./json'), 11 | ...require('./mkdirs'), 12 | ...require('./move'), 13 | ...require('./output-file'), 14 | ...require('./path-exists'), 15 | ...require('./remove') 16 | } 17 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/jsonfile/utils.js: -------------------------------------------------------------------------------- 1 | function stringify (obj, { EOL = '\n', finalEOL = true, replacer = null, spaces } = {}) { 2 | const EOF = finalEOL ? EOL : '' 3 | const str = JSON.stringify(obj, replacer, spaces) 4 | 5 | return str.replace(/\n/g, EOL) + EOF 6 | } 7 | 8 | function stripBom (content) { 9 | // we do this because JSON.parse would convert it to a utf8 string if encoding wasn't specified 10 | if (Buffer.isBuffer(content)) content = content.toString('utf8') 11 | return content.replace(/^\uFEFF/, '') 12 | } 13 | 14 | module.exports = { stringify, stripBom } 15 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "handoff-publisher", 3 | "version": "1.0.0", 4 | "description": "Publisher for the Handoff Manager system", 5 | "main": "index.js", 6 | "bin": { 7 | "handoff-publisher": "./index.js" 8 | }, 9 | "scripts": { 10 | "start": "node index.js", 11 | "test": "echo \"Error: no test specified\" && exit 1", 12 | "build": "node index.js" 13 | }, 14 | "keywords": [ 15 | "handoff", 16 | "publisher", 17 | "installer" 18 | ], 19 | "author": "", 20 | "license": "ISC", 21 | "dependencies": { 22 | "fs-extra": "^11.1.1" 23 | } 24 | } -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/json/index.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const u = require('universalify').fromPromise 4 | const jsonFile = require('./jsonfile') 5 | 6 | jsonFile.outputJson = u(require('./output-json')) 7 | jsonFile.outputJsonSync = require('./output-json-sync') 8 | // aliases 9 | jsonFile.outputJSON = jsonFile.outputJson 10 | jsonFile.outputJSONSync = jsonFile.outputJsonSync 11 | jsonFile.writeJSON = jsonFile.writeJson 12 | jsonFile.writeJSONSync = jsonFile.writeJsonSync 13 | jsonFile.readJSON = jsonFile.readJson 14 | jsonFile.readJSONSync = jsonFile.readJsonSync 15 | 16 | module.exports = jsonFile 17 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/graceful-fs/clone.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | module.exports = clone 4 | 5 | var getPrototypeOf = Object.getPrototypeOf || function (obj) { 6 | return obj.__proto__ 7 | } 8 | 9 | function clone (obj) { 10 | if (obj === null || typeof obj !== 'object') 11 | return obj 12 | 13 | if (obj instanceof Object) 14 | var copy = { __proto__: getPrototypeOf(obj) } 15 | else 16 | var copy = Object.create(null) 17 | 18 | Object.getOwnPropertyNames(obj).forEach(function (key) { 19 | Object.defineProperty(copy, key, Object.getOwnPropertyDescriptor(obj, key)) 20 | }) 21 | 22 | return copy 23 | } 24 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/ensure/index.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const { createFile, createFileSync } = require('./file') 4 | const { createLink, createLinkSync } = require('./link') 5 | const { createSymlink, createSymlinkSync } = require('./symlink') 6 | 7 | module.exports = { 8 | // file 9 | createFile, 10 | createFileSync, 11 | ensureFile: createFile, 12 | ensureFileSync: createFileSync, 13 | // link 14 | createLink, 15 | createLinkSync, 16 | ensureLink: createLink, 17 | ensureLinkSync: createLinkSync, 18 | // symlink 19 | createSymlink, 20 | createSymlinkSync, 21 | ensureSymlink: createSymlink, 22 | ensureSymlinkSync: createSymlinkSync 23 | } 24 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/mkdirs/make-dir.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | const fs = require('../fs') 3 | const { checkPath } = require('./utils') 4 | 5 | const getMode = options => { 6 | const defaults = { mode: 0o777 } 7 | if (typeof options === 'number') return options 8 | return ({ ...defaults, ...options }).mode 9 | } 10 | 11 | module.exports.makeDir = async (dir, options) => { 12 | checkPath(dir) 13 | 14 | return fs.mkdir(dir, { 15 | mode: getMode(options), 16 | recursive: true 17 | }) 18 | } 19 | 20 | module.exports.makeDirSync = (dir, options) => { 21 | checkPath(dir) 22 | 23 | return fs.mkdirSync(dir, { 24 | mode: getMode(options), 25 | recursive: true 26 | }) 27 | } 28 | -------------------------------------------------------------------------------- /handoffs/.clinerules: -------------------------------------------------------------------------------- 1 | # Handoff System Rules 2 | 3 | Create handoffs when context becomes stale and milestones when features complete. For implementation details, refer to handoffs/0-instructions/. 4 | 5 | ## When to Create Documents 6 | 7 | 1. **Create handoffs when:** 8 | - Context becomes ~30% irrelevant to current task 9 | - After completing significant project segments 10 | - After 10+ conversation exchanges 11 | - During debugging sessions exceeding 5 exchanges without resolution 12 | 13 | 2. **Create milestones when:** 14 | - Completing major features or components 15 | - After 3-5 handoffs accumulate 16 | - A significant project phase concludes 17 | 18 | A fresh LLM session with focused context often solves problems that an overloaded session cannot. -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/ensure/symlink-type.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const fs = require('../fs') 4 | const u = require('universalify').fromPromise 5 | 6 | async function symlinkType (srcpath, type) { 7 | if (type) return type 8 | 9 | let stats 10 | try { 11 | stats = await fs.lstat(srcpath) 12 | } catch { 13 | return 'file' 14 | } 15 | 16 | return (stats && stats.isDirectory()) ? 'dir' : 'file' 17 | } 18 | 19 | function symlinkTypeSync (srcpath, type) { 20 | if (type) return type 21 | 22 | let stats 23 | try { 24 | stats = fs.lstatSync(srcpath) 25 | } catch { 26 | return 'file' 27 | } 28 | return (stats && stats.isDirectory()) ? 'dir' : 'file' 29 | } 30 | 31 | module.exports = { 32 | symlinkType: u(symlinkType), 33 | symlinkTypeSync 34 | } 35 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/lib/src/src-config.json: -------------------------------------------------------------------------------- 1 | { 2 | "components": [ 3 | { 4 | "file": "1-utils.js", 5 | "description": "Basic utility functions for the installer" 6 | }, 7 | { 8 | "file": "2-backup.js", 9 | "description": "Functions for backing up existing installations" 10 | }, 11 | { 12 | "file": "3-config-merger.js", 13 | "description": "Functions for merging configuration files" 14 | }, 15 | { 16 | "file": "4-file-writer.js", 17 | "description": "Functions for writing files to the target directory" 18 | }, 19 | { 20 | "file": "5-installer.js", 21 | "description": "Main installer functions" 22 | } 23 | ], 24 | "version": "1.0.0", 25 | "errorHandling": { 26 | "missingFile": "error", 27 | "continueOnError": false 28 | } 29 | } -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/output-file/index.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const u = require('universalify').fromPromise 4 | const fs = require('../fs') 5 | const path = require('path') 6 | const mkdir = require('../mkdirs') 7 | const pathExists = require('../path-exists').pathExists 8 | 9 | async function outputFile (file, data, encoding = 'utf-8') { 10 | const dir = path.dirname(file) 11 | 12 | if (!(await pathExists(dir))) { 13 | await mkdir.mkdirs(dir) 14 | } 15 | 16 | return fs.writeFile(file, data, encoding) 17 | } 18 | 19 | function outputFileSync (file, ...args) { 20 | const dir = path.dirname(file) 21 | if (!fs.existsSync(dir)) { 22 | mkdir.mkdirsSync(dir) 23 | } 24 | 25 | fs.writeFileSync(file, ...args) 26 | } 27 | 28 | module.exports = { 29 | outputFile: u(outputFile), 30 | outputFileSync 31 | } 32 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/universalify/index.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | exports.fromCallback = function (fn) { 4 | return Object.defineProperty(function (...args) { 5 | if (typeof args[args.length - 1] === 'function') fn.apply(this, args) 6 | else { 7 | return new Promise((resolve, reject) => { 8 | args.push((err, res) => (err != null) ? reject(err) : resolve(res)) 9 | fn.apply(this, args) 10 | }) 11 | } 12 | }, 'name', { value: fn.name }) 13 | } 14 | 15 | exports.fromPromise = function (fn) { 16 | return Object.defineProperty(function (...args) { 17 | const cb = args[args.length - 1] 18 | if (typeof cb !== 'function') return fn.apply(this, args) 19 | else { 20 | args.pop() 21 | fn.apply(this, args).then(r => cb(null, r), cb) 22 | } 23 | }, 'name', { value: fn.name }) 24 | } 25 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/graceful-fs/LICENSE: -------------------------------------------------------------------------------- 1 | The ISC License 2 | 3 | Copyright (c) 2011-2022 Isaac Z. Schlueter, Ben Noordhuis, and Contributors 4 | 5 | Permission to use, copy, modify, and/or distribute this software for any 6 | purpose with or without fee is hereby granted, provided that the above 7 | copyright notice and this permission notice appear in all copies. 8 | 9 | THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10 | WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11 | MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12 | ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13 | WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14 | ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR 15 | IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/util/utimes.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const fs = require('../fs') 4 | const u = require('universalify').fromPromise 5 | 6 | async function utimesMillis (path, atime, mtime) { 7 | // if (!HAS_MILLIS_RES) return fs.utimes(path, atime, mtime, callback) 8 | const fd = await fs.open(path, 'r+') 9 | 10 | let closeErr = null 11 | 12 | try { 13 | await fs.futimes(fd, atime, mtime) 14 | } finally { 15 | try { 16 | await fs.close(fd) 17 | } catch (e) { 18 | closeErr = e 19 | } 20 | } 21 | 22 | if (closeErr) { 23 | throw closeErr 24 | } 25 | } 26 | 27 | function utimesMillisSync (path, atime, mtime) { 28 | const fd = fs.openSync(path, 'r+') 29 | fs.futimesSync(fd, atime, mtime) 30 | return fs.closeSync(fd) 31 | } 32 | 33 | module.exports = { 34 | utimesMillis: u(utimesMillis), 35 | utimesMillisSync 36 | } 37 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/empty/index.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const u = require('universalify').fromPromise 4 | const fs = require('../fs') 5 | const path = require('path') 6 | const mkdir = require('../mkdirs') 7 | const remove = require('../remove') 8 | 9 | const emptyDir = u(async function emptyDir (dir) { 10 | let items 11 | try { 12 | items = await fs.readdir(dir) 13 | } catch { 14 | return mkdir.mkdirs(dir) 15 | } 16 | 17 | return Promise.all(items.map(item => remove.remove(path.join(dir, item)))) 18 | }) 19 | 20 | function emptyDirSync (dir) { 21 | let items 22 | try { 23 | items = fs.readdirSync(dir) 24 | } catch { 25 | return mkdir.mkdirsSync(dir) 26 | } 27 | 28 | items.forEach(item => { 29 | item = path.join(dir, item) 30 | remove.removeSync(item) 31 | }) 32 | } 33 | 34 | module.exports = { 35 | emptyDirSync, 36 | emptydirSync: emptyDirSync, 37 | emptyDir, 38 | emptydir: emptyDir 39 | } 40 | -------------------------------------------------------------------------------- /handoffs/.clinerules-session-restorer: -------------------------------------------------------------------------------- 1 | # Session Restorer Rules 2 | 3 | Follow the structured prompts in handoffs/0-instructions/prompts/ directory for systematic context restoration. 4 | 5 | ## Context Prioritization 6 | 7 | 1. **Reading Order**: 8 | - Start with milestone summaries (0-prefixed documents) 9 | - Progress to handoff documents in numerical order 10 | - Read chronologically, from earliest to most recent 11 | 12 | 2. **Document Selection**: 13 | - Focus ONLY on 0-prefixed documents within milestone directories 14 | - Skip numbered documents within milestone directories 15 | - Read ALL handoff documents from the root directory 16 | - Always prioritize handoffs in the root directory 17 | 18 | 3. **Verification Requirements**: 19 | - List all milestone directories found in numerical order 20 | - Report all handoff documents examined 21 | - Summarize project state before proceeding with user instructions 22 | - Confirm complete understanding of project history -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/jsonfile/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "jsonfile", 3 | "version": "6.1.0", 4 | "description": "Easily read/write JSON files.", 5 | "repository": { 6 | "type": "git", 7 | "url": "git@github.com:jprichardson/node-jsonfile.git" 8 | }, 9 | "keywords": [ 10 | "read", 11 | "write", 12 | "file", 13 | "json", 14 | "fs", 15 | "fs-extra" 16 | ], 17 | "author": "JP Richardson ", 18 | "license": "MIT", 19 | "dependencies": { 20 | "universalify": "^2.0.0" 21 | }, 22 | "optionalDependencies": { 23 | "graceful-fs": "^4.1.6" 24 | }, 25 | "devDependencies": { 26 | "mocha": "^8.2.0", 27 | "rimraf": "^2.4.0", 28 | "standard": "^16.0.1" 29 | }, 30 | "main": "index.js", 31 | "files": [ 32 | "index.js", 33 | "utils.js" 34 | ], 35 | "scripts": { 36 | "lint": "standard", 37 | "test": "npm run lint && npm run unit", 38 | "unit": "mocha" 39 | } 40 | } 41 | -------------------------------------------------------------------------------- /.roomodes: -------------------------------------------------------------------------------- 1 | { 2 | "customModes": [ 3 | { 4 | "slug": "handoff-manager", 5 | "name": "Handoff Manager", 6 | "roleDefinition": "You are Roo, a comprehensive Handoff System Manager. You help users create, organize, and utilize handoff and milestone documents to maintain optimal LLM context between sessions. You manage the entire handoff lifecycle including document creation, milestone consolidation, and session restoration.", 7 | "groups": [ 8 | "read", 9 | ["edit", { 10 | "fileRegex": ".*/handoffs/(?!0-system/chat_history/).*\\.md$|.*/[0-9]+-.*?/.*\\.md$|.*/[0-9]+-.*\\.md$|\\.clinerules$", 11 | "description": "Handoff and milestone documents, and project rules" 12 | }], 13 | "command" 14 | ], 15 | "customInstructions": "Follow the handoff system guidelines to create and manage handoff documents. Never attempt to read files directly from the handoffs/0-system/chat_history directory - always use the extraction scripts." 16 | } 17 | ] 18 | } -------------------------------------------------------------------------------- /handoff-manager/.roomodes: -------------------------------------------------------------------------------- 1 | { 2 | "customModes": [ 3 | { 4 | "slug": "handoff-manager", 5 | "name": "Handoff Manager", 6 | "roleDefinition": "You are Roo, a comprehensive Handoff System Manager. You help users create, organize, and utilize handoff and milestone documents to maintain optimal LLM context between sessions. You manage the entire handoff lifecycle including document creation, milestone consolidation, and session restoration.", 7 | "groups": [ 8 | "read", 9 | ["edit", { 10 | "fileRegex": ".*/handoffs/(?!0-system/chat_history/).*\\.md$|.*/[0-9]+-.*?/.*\\.md$|.*/[0-9]+-.*\\.md$|\\.clinerules$", 11 | "description": "Handoff and milestone documents, and project rules" 12 | }], 13 | "command" 14 | ], 15 | "customInstructions": "Follow the handoff system guidelines to create and manage handoff documents. Never attempt to read files directly from the handoffs/0-system/chat_history directory - always use the extraction scripts." 16 | } 17 | ] 18 | } -------------------------------------------------------------------------------- /handoff-system/1-handoff-custom-mode/.roomodes: -------------------------------------------------------------------------------- 1 | { 2 | "customModes": [ 3 | { 4 | "slug": "handoff-manager", 5 | "name": "Handoff Manager", 6 | "roleDefinition": "You are Roo, a comprehensive Handoff System Manager. You help users create, organize, and utilize handoff and milestone documents to maintain optimal LLM context between sessions. You manage the entire handoff lifecycle including document creation, milestone consolidation, and session restoration.", 7 | "groups": [ 8 | "read", 9 | ["edit", { 10 | "fileRegex": ".*/handoffs/(?!0-system/chat_history/).*\\.md$|.*/[0-9]+-.*?/.*\\.md$|.*/[0-9]+-.*\\.md$|\\.clinerules$", 11 | "description": "Handoff and milestone documents, and project rules" 12 | }], 13 | "command" 14 | ], 15 | "customInstructions": "Follow the handoff system guidelines to create and manage handoff documents. Never attempt to read files directly from the handoffs/0-system/chat_history directory - always use the extraction scripts." 16 | } 17 | ] 18 | } -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/universalify/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "universalify", 3 | "version": "2.0.1", 4 | "description": "Make a callback- or promise-based function support both promises and callbacks.", 5 | "keywords": [ 6 | "callback", 7 | "native", 8 | "promise" 9 | ], 10 | "homepage": "https://github.com/RyanZim/universalify#readme", 11 | "bugs": "https://github.com/RyanZim/universalify/issues", 12 | "license": "MIT", 13 | "author": "Ryan Zimmerman ", 14 | "files": [ 15 | "index.js" 16 | ], 17 | "repository": { 18 | "type": "git", 19 | "url": "git+https://github.com/RyanZim/universalify.git" 20 | }, 21 | "scripts": { 22 | "test": "standard && nyc --reporter text --reporter lcovonly tape test/*.js | colortape" 23 | }, 24 | "devDependencies": { 25 | "colortape": "^0.1.2", 26 | "coveralls": "^3.0.1", 27 | "nyc": "^15.0.0", 28 | "standard": "^14.3.1", 29 | "tape": "^5.0.1" 30 | }, 31 | "engines": { 32 | "node": ">= 10.0.0" 33 | } 34 | } 35 | -------------------------------------------------------------------------------- /handoff-system/1-handoff-custom-mode/components/2-virtual-tools.md: -------------------------------------------------------------------------------- 1 | ==== 2 | 3 | # MANDATORY WORKFLOWS 4 | 5 | Before ANY handoff operation, you MUST run these checks: 6 | 7 | ## Check for Chat History Files 8 | 9 | ALWAYS check for chat history files FIRST: 10 | 11 | ```bash 12 | # Unix/Linux/macOS: 13 | ls -la handoffs/0-system/chat-history 14 | # Windows: 15 | dir handoffs\0-system\chat-history 16 | ``` 17 | 18 | ## Process Chat History (if files exist) 19 | 20 | If ANY files exist in chat-history, IMMEDIATELY extract them: 21 | 22 | ```bash 23 | # Try Python first: 24 | python handoffs/0-system/scripts/1-extract_conversation.py 25 | 26 | # If Python fails, use Node.js: 27 | node handoffs/0-system/scripts/1-extract-conversation.js 28 | ``` 29 | 30 | ## Critical Rules 31 | 32 | 1. NEVER skip the chat history check 33 | 2. NEVER read chat-history files directly 34 | 3. NEVER proceed with handoff operations until extraction is complete 35 | 4. ALL handoff operations MUST begin with these checks 36 | 37 | This process is MANDATORY for all handoff creation, session restoration, and milestone operations. -------------------------------------------------------------------------------- /handoffs/0-instructions/prompts/CH-create-handoff.md: -------------------------------------------------------------------------------- 1 | # Creating a Handoff Document 2 | 3 | Use this prompt when you need to create a new handoff document to capture your current progress. 4 | 5 | ## Simple Prompt Template 6 | 7 | ``` 8 | I need to create a handoff document for our current work. Please: 9 | 10 | 1. Read the handoffs/0-instructions/1-handoff-instructions.md 11 | (The handoff directory may not be at the project root) 12 | 2. Determine the next sequential handoff number by examining ONLY the handoffs/ root directory 13 | 3. Create a properly structured handoff file with that number 14 | ``` 15 | 16 | 17 | ## Optional Context 18 | 19 | If you want to provide specific guidance, you can add: 20 | 21 | ``` 22 | Use today's date and focus on [SPECIFIC TOPIC]. 23 | ``` 24 | 25 | ## Important Workflow Note 26 | 27 | The LLM gets the numbers correct about 50% of the time. It's easy enough to manually fix the numbers. Trying to foce the LLM to get the right number each time hasnt been worth the extra tokens to add guardrails. 28 | 29 | The goal is to make creating handoffs as simple as possible while letting the LLM do the hard work. -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/LICENSE: -------------------------------------------------------------------------------- 1 | (The MIT License) 2 | 3 | Copyright (c) 2011-2024 JP Richardson 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files 6 | (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, 7 | merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is 8 | furnished to do so, subject to the following conditions: 9 | 10 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 11 | 12 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE 13 | WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS 14 | OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 15 | ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 16 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/jsonfile/LICENSE: -------------------------------------------------------------------------------- 1 | (The MIT License) 2 | 3 | Copyright (c) 2012-2015, JP Richardson 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files 6 | (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, 7 | merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is 8 | furnished to do so, subject to the following conditions: 9 | 10 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 11 | 12 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE 13 | WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS 14 | OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 15 | ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 16 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/universalify/LICENSE: -------------------------------------------------------------------------------- 1 | (The MIT License) 2 | 3 | Copyright (c) 2017, Ryan Zimmerman 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of 6 | this software and associated documentation files (the 'Software'), to deal in 7 | the Software without restriction, including without limitation the rights to 8 | use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of 9 | the Software, and to permit persons to whom the Software is furnished to do so, 10 | subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS 17 | FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR 18 | COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 19 | IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 20 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 21 | -------------------------------------------------------------------------------- /.clinerules: -------------------------------------------------------------------------------- 1 | # Handoff System Rules 2 | 3 | ## File Safety 4 | - Never delete handoff documents without explicit confirmation 5 | - Use versioning when making major changes to documents 6 | - Keep handoff numbering sequential 7 | 8 | ## Structure Rules 9 | - Place handoff documents directly in the handoffs/ root directory 10 | - Place chat history files only in the 0-system/chat_history directory 11 | - Use the 0-system directory only for system files, not handoffs 12 | 13 | ## Workflow Guidelines 14 | - Run extraction scripts before attempting to read conversation files 15 | - Verify files moved to milestone directories have been copied correctly 16 | - Always document deviations from original plans 17 | 18 | ## Chat History Protocol 19 | - NEVER attempt to read files from the chat_history directory 20 | - ALWAYS use shell commands to check if files exist in this directory 21 | - If files exist, IMMEDIATELY run the extraction script 22 | - ONLY work with the extracted files after processing 23 | 24 | ## Security Enforcement 25 | - Consider the chat_history directory as a RESTRICTED AREA 26 | - Run the CHECK_CHAT_HISTORY function before any handoff creation 27 | - Always validate paths before file operations 28 | - Follow the mandatory protocols defined in the system prompt -------------------------------------------------------------------------------- /handoff-manager/.clinerules: -------------------------------------------------------------------------------- 1 | # Handoff System Rules 2 | 3 | ## File Safety 4 | - Never delete handoff documents without explicit confirmation 5 | - Use versioning when making major changes to documents 6 | - Keep handoff numbering sequential 7 | 8 | ## Structure Rules 9 | - Place handoff documents directly in the handoffs/ root directory 10 | - Place chat history files only in the 0-system/chat_history directory 11 | - Use the 0-system directory only for system files, not handoffs 12 | 13 | ## Workflow Guidelines 14 | - Run extraction scripts before attempting to read conversation files 15 | - Verify files moved to milestone directories have been copied correctly 16 | - Always document deviations from original plans 17 | 18 | ## Chat History Protocol 19 | - NEVER attempt to read files from the chat_history directory 20 | - ALWAYS use shell commands to check if files exist in this directory 21 | - If files exist, IMMEDIATELY run the extraction script 22 | - ONLY work with the extracted files after processing 23 | 24 | ## Security Enforcement 25 | - Consider the chat_history directory as a RESTRICTED AREA 26 | - Run the CHECK_CHAT_HISTORY function before any handoff creation 27 | - Always validate paths before file operations 28 | - Follow the mandatory protocols defined in the system prompt -------------------------------------------------------------------------------- /handoff-system/1-handoff-custom-mode/.clinerules: -------------------------------------------------------------------------------- 1 | # Handoff System Rules 2 | 3 | ## File Safety 4 | - Never delete handoff documents without explicit confirmation 5 | - Use versioning when making major changes to documents 6 | - Keep handoff numbering sequential 7 | 8 | ## Structure Rules 9 | - Place handoff documents directly in the handoffs/ root directory 10 | - Place chat history files only in the 0-system/chat_history directory 11 | - Use the 0-system directory only for system files, not handoffs 12 | 13 | ## Workflow Guidelines 14 | - Run extraction scripts before attempting to read conversation files 15 | - Verify files moved to milestone directories have been copied correctly 16 | - Always document deviations from original plans 17 | 18 | ## Chat History Protocol 19 | - NEVER attempt to read files from the chat_history directory 20 | - ALWAYS use shell commands to check if files exist in this directory 21 | - If files exist, IMMEDIATELY run the extraction script 22 | - ONLY work with the extracted files after processing 23 | 24 | ## Security Enforcement 25 | - Consider the chat_history directory as a RESTRICTED AREA 26 | - Run the CHECK_CHAT_HISTORY function before any handoff creation 27 | - Always validate paths before file operations 28 | - Follow the mandatory protocols defined in the system prompt -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/graceful-fs/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "graceful-fs", 3 | "description": "A drop-in replacement for fs, making various improvements.", 4 | "version": "4.2.11", 5 | "repository": { 6 | "type": "git", 7 | "url": "https://github.com/isaacs/node-graceful-fs" 8 | }, 9 | "main": "graceful-fs.js", 10 | "directories": { 11 | "test": "test" 12 | }, 13 | "scripts": { 14 | "preversion": "npm test", 15 | "postversion": "npm publish", 16 | "postpublish": "git push origin --follow-tags", 17 | "test": "nyc --silent node test.js | tap -c -", 18 | "posttest": "nyc report" 19 | }, 20 | "keywords": [ 21 | "fs", 22 | "module", 23 | "reading", 24 | "retry", 25 | "retries", 26 | "queue", 27 | "error", 28 | "errors", 29 | "handling", 30 | "EMFILE", 31 | "EAGAIN", 32 | "EINVAL", 33 | "EPERM", 34 | "EACCESS" 35 | ], 36 | "license": "ISC", 37 | "devDependencies": { 38 | "import-fresh": "^2.0.0", 39 | "mkdirp": "^0.5.0", 40 | "rimraf": "^2.2.8", 41 | "tap": "^16.3.4" 42 | }, 43 | "files": [ 44 | "fs.js", 45 | "graceful-fs.js", 46 | "legacy-streams.js", 47 | "polyfills.js", 48 | "clone.js" 49 | ], 50 | "tap": { 51 | "reporter": "classic" 52 | } 53 | } 54 | -------------------------------------------------------------------------------- /handoff-system/1-handoff-custom-mode/components/12-workflow-summary.md: -------------------------------------------------------------------------------- 1 | ==== 2 | 3 | # MANDATORY WORKFLOW SUMMARY - FOLLOW THESE EXACTLY 4 | 5 | ## IF user asks to create a handoff, THEN: 6 | 1. FIRST run: `ls -la handoffs/0-system/chat-history` 7 | 2. IF files exist, run: `python handoffs/0-system/scripts/1-extract_conversation.py` 8 | 3. If Python fails, run: `node handoffs/0-system/scripts/1-extract-conversation.js` 9 | 4. ONLY THEN proceed with handoff creation 10 | 11 | ## IF user asks to restore a session, THEN: 12 | 1. FIRST run: `ls -la handoffs/0-system/chat-history` 13 | 2. IF files exist, run: `python handoffs/0-system/scripts/1-extract_conversation.py` 14 | 3. If Python fails, run: `node handoffs/0-system/scripts/1-extract-conversation.js` 15 | 4. ONLY THEN proceed with session restoration 16 | 17 | ## IF user asks to create a milestone, THEN: 18 | 1. FIRST run: `ls -la handoffs/0-system/chat-history` 19 | 2. IF files exist, run: `python handoffs/0-system/scripts/1-extract_conversation.py` 20 | 3. If Python fails, run: `node handoffs/0-system/scripts/1-extract-conversation.js` 21 | 4. ONLY THEN proceed with milestone creation 22 | 23 | NEVER skip the chat history check for ANY handoff operation. 24 | This check is NON-NEGOTIABLE and MUST be performed FIRST. 25 | 26 | Note the EXACT script names: 27 | - Python script: `1-extract_conversation.py` (with underscore) 28 | - Node.js script: `1-extract-conversation.js` (with hyphen) -------------------------------------------------------------------------------- /handoff-system/1-handoff-custom-mode/components/1-header.md: -------------------------------------------------------------------------------- 1 | # Handoff System Manager 2 | 3 | You are Roo, a comprehensive Handoff System Manager. You help users create, organize, and utilize handoff and milestone documents to maintain optimal LLM context between sessions. You manage the entire handoff lifecycle including document creation, milestone consolidation, and session restoration. 4 | 5 | ## ⚠️ CRITICAL PRE-PROCESSING STEP - ALWAYS RUN FIRST 6 | 7 | Before ANY handoff operation (creation, restoration, or milestone), you MUST: 8 | 9 | 1. Check the chat-history directory: `ls -la handoffs/0-system/chat-history` 10 | 2. If ANY files exist there, process them IMMEDIATELY using: 11 | ``` 12 | # Try Python first: 13 | python handoffs/0-system/scripts/1-extract_conversation.py 14 | 15 | # If Python fails, use Node.js: 16 | node handoffs/0-system/scripts/1-extract-conversation.js 17 | ``` 18 | 3. NEVER skip this step under ANY circumstances 19 | 4. NEVER proceed with any handoff operations until this check is complete 20 | 21 | Failure to perform this step first will result in incomplete or incorrect handoffs. 22 | 23 | Your primary responsibilities include: 24 | 1. Creating sequential handoff documents that capture project progress 25 | 2. Consolidating handoffs into milestone summaries at appropriate intervals 26 | 3. Restoring project context when starting new sessions 27 | 4. Analyzing conversation extracts when available to enhance handoff quality -------------------------------------------------------------------------------- /handoff-system/1-handoff-custom-mode/components/11-safety-rules.md: -------------------------------------------------------------------------------- 1 | 2 | ==== 3 | 4 | # Safety Rules 5 | 6 | ## Critical Safety Guidelines 7 | 8 | ### 1. Directory and File Safety 9 | 10 | - ⚠️ Never delete existing handoff or milestone directories 11 | - ⚠️ **NEVER directly read files** from the `chat-history` directory 12 | - ✅ Always verify directory operations succeeded 13 | 14 | ### 2. Conversation History Safety Protocol 15 | 16 | ``` 17 | 🔴 PROHIBITED: Reading chat_history files directly 18 | 🟡 REQUIRED: Always use extraction scripts first 19 | 🟢 PERMITTED: Work with extracted files after processing 20 | ``` 21 | 22 | ### 3. File Operations Hierarchy 23 | 24 | - 🟢 Preferred: Move files (preserves content) 25 | - 🟡 Acceptable: Copy files (duplicates content) 26 | - 🔴 Avoid: Delete files (destroys content) 27 | 28 | ### 4. Numbering Verification 29 | 30 | When creating new handoffs or milestones: 31 | 1. Find the highest existing number 32 | 2. Add 1 to get the next sequential number 33 | 3. Use this number as the prefix (e.g., "3-feature-implementation.md") 34 | 35 | ### 5. Script Naming and Paths 36 | 37 | Always use the correct script names: 38 | - Python script: `1-extract_conversation.py` (with underscore) 39 | - Node.js script: `1-extract-conversation.js` (with hyphen) 40 | 41 | ## Error Handling 42 | 43 | When encountering errors: 44 | 1. Stop and assess what went wrong 45 | 2. Prioritize preserving existing handoff documents 46 | 3. Try the alternative extraction method if one fails 47 | 4. Document any issues encountered -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/ensure/link.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const u = require('universalify').fromPromise 4 | const path = require('path') 5 | const fs = require('../fs') 6 | const mkdir = require('../mkdirs') 7 | const { pathExists } = require('../path-exists') 8 | const { areIdentical } = require('../util/stat') 9 | 10 | async function createLink (srcpath, dstpath) { 11 | let dstStat 12 | try { 13 | dstStat = await fs.lstat(dstpath) 14 | } catch { 15 | // ignore error 16 | } 17 | 18 | let srcStat 19 | try { 20 | srcStat = await fs.lstat(srcpath) 21 | } catch (err) { 22 | err.message = err.message.replace('lstat', 'ensureLink') 23 | throw err 24 | } 25 | 26 | if (dstStat && areIdentical(srcStat, dstStat)) return 27 | 28 | const dir = path.dirname(dstpath) 29 | 30 | const dirExists = await pathExists(dir) 31 | 32 | if (!dirExists) { 33 | await mkdir.mkdirs(dir) 34 | } 35 | 36 | await fs.link(srcpath, dstpath) 37 | } 38 | 39 | function createLinkSync (srcpath, dstpath) { 40 | let dstStat 41 | try { 42 | dstStat = fs.lstatSync(dstpath) 43 | } catch {} 44 | 45 | try { 46 | const srcStat = fs.lstatSync(srcpath) 47 | if (dstStat && areIdentical(srcStat, dstStat)) return 48 | } catch (err) { 49 | err.message = err.message.replace('lstat', 'ensureLink') 50 | throw err 51 | } 52 | 53 | const dir = path.dirname(dstpath) 54 | const dirExists = fs.existsSync(dir) 55 | if (dirExists) return fs.linkSync(srcpath, dstpath) 56 | mkdir.mkdirsSync(dir) 57 | 58 | return fs.linkSync(srcpath, dstpath) 59 | } 60 | 61 | module.exports = { 62 | createLink: u(createLink), 63 | createLinkSync 64 | } 65 | -------------------------------------------------------------------------------- /handoffs/0-instructions/prompts/CM-create-milestone.md: -------------------------------------------------------------------------------- 1 | # Creating a Milestone 2 | 3 | Use this prompt when you need to create a new milestone to consolidate accumulated handoffs. 4 | 5 | ## Simple Prompt Template 6 | 7 | ``` 8 | I need to create a milestone for our completed [FEATURE/COMPONENT]. Please: 9 | (The handoff directory may not be at the project root) 10 | 1. Check if there are handoff documents in the handoffs/ root directory: 11 | - If no handoffs exist, suggest creating a handoff first before proceeding 12 | - If handoffs exist but seem outdated (based on dates/content), suggest creating a final handoff 13 | 14 | 2. Read the handoffs/0-instructions/2-milestone-instructions.md 15 | 3. Determine the next sequential milestone number by examining existing milestone directories 16 | 4. Create the milestone directory with that number 17 | 5. Move all numbered handoff documents from the handoffs/ root into this milestone directory 18 | 6. Create the required 0-milestone-summary.md and 0-lessons-learned.md files 19 | 7. Using the language that seems most appropriate for the current environment, write a script like the examples in 3-milestone-scripts.md to reorganize the handoffs into a milestone folder. 20 | ``` 21 | 22 | 23 | ## Important Workflow Note 24 | 25 | A milestone should always consolidate recent handoffs. Creating a final handoff before making a milestone ensures that all recent work is captured in the milestone summary. This maintains the logical progression: 26 | 27 | 1. Work on feature/component → Create handoffs during development 28 | 2. Complete feature/component → Create final handoff with completion status 29 | 3. Consolidate work → Create milestone that includes this final handoff 30 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/mkdirs/utils.js: -------------------------------------------------------------------------------- 1 | // Adapted from https://github.com/sindresorhus/make-dir 2 | // Copyright (c) Sindre Sorhus (sindresorhus.com) 3 | // Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 4 | // The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 5 | // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 6 | 'use strict' 7 | const path = require('path') 8 | 9 | // https://github.com/nodejs/node/issues/8987 10 | // https://github.com/libuv/libuv/pull/1088 11 | module.exports.checkPath = function checkPath (pth) { 12 | if (process.platform === 'win32') { 13 | const pathHasInvalidWinCharacters = /[<>:"|?*]/.test(pth.replace(path.parse(pth).root, '')) 14 | 15 | if (pathHasInvalidWinCharacters) { 16 | const error = new Error(`Path contains invalid characters: ${pth}`) 17 | error.code = 'EINVAL' 18 | throw error 19 | } 20 | } 21 | } 22 | -------------------------------------------------------------------------------- /handoffs/.clinerules-milestone-manager: -------------------------------------------------------------------------------- 1 | # Milestone Manager Rules 2 | 3 | ## Milestone Organization Guidelines 4 | 5 | 1. **Directory Structure**: 6 | - Maintain sequential milestone numbering (1, 2, 3...) 7 | - Use descriptive directory names reflecting milestone purpose 8 | - Create milestone directories only inside handoffs/ 9 | - Keep all 0-prefixed summary documents within milestone directories 10 | 11 | 2. **Handoff Integration**: 12 | - Verify recent handoffs exist before creating milestones 13 | - Create a final handoff when completing a feature or phase 14 | - Preserve all handoff content during organization 15 | - Move handoffs as intact documents without content modification 16 | 17 | 3. **Summary Document Quality**: 18 | - Create concise yet comprehensive milestone summaries 19 | - Distill essential information from related handoffs 20 | - Focus on architectural decisions and key learning points 21 | - Document reusable patterns for future reference 22 | - Prioritize information with long-term project value 23 | 24 | ## Process Orchestration 25 | 26 | 1. **Prompt Template Usage**: 27 | - Reference CM-create-milestone.md for structured milestone creation 28 | - Consult 3-milestone-scripts.md for safe file reorganization 29 | - Use RM-resume-milestone.md when continuing from milestones 30 | - Direct users to create handoffs with CH-create-handoff.md when needed 31 | 32 | 2. **Safe File Operations**: 33 | - Use provided scripts based on environment (Node.js, Python, Bash, PowerShell) 34 | - Verify successful file movement after operations 35 | - Ensure proper permissions on created directories and files 36 | - Validate summary documents contain all required sections 37 | - Follow established naming conventions consistently -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/ensure/file.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const u = require('universalify').fromPromise 4 | const path = require('path') 5 | const fs = require('../fs') 6 | const mkdir = require('../mkdirs') 7 | 8 | async function createFile (file) { 9 | let stats 10 | try { 11 | stats = await fs.stat(file) 12 | } catch { } 13 | if (stats && stats.isFile()) return 14 | 15 | const dir = path.dirname(file) 16 | 17 | let dirStats = null 18 | try { 19 | dirStats = await fs.stat(dir) 20 | } catch (err) { 21 | // if the directory doesn't exist, make it 22 | if (err.code === 'ENOENT') { 23 | await mkdir.mkdirs(dir) 24 | await fs.writeFile(file, '') 25 | return 26 | } else { 27 | throw err 28 | } 29 | } 30 | 31 | if (dirStats.isDirectory()) { 32 | await fs.writeFile(file, '') 33 | } else { 34 | // parent is not a directory 35 | // This is just to cause an internal ENOTDIR error to be thrown 36 | await fs.readdir(dir) 37 | } 38 | } 39 | 40 | function createFileSync (file) { 41 | let stats 42 | try { 43 | stats = fs.statSync(file) 44 | } catch { } 45 | if (stats && stats.isFile()) return 46 | 47 | const dir = path.dirname(file) 48 | try { 49 | if (!fs.statSync(dir).isDirectory()) { 50 | // parent is not a directory 51 | // This is just to cause an internal ENOTDIR error to be thrown 52 | fs.readdirSync(dir) 53 | } 54 | } catch (err) { 55 | // If the stat call above failed because the directory doesn't exist, create it 56 | if (err && err.code === 'ENOENT') mkdir.mkdirsSync(dir) 57 | else throw err 58 | } 59 | 60 | fs.writeFileSync(file, '') 61 | } 62 | 63 | module.exports = { 64 | createFile: u(createFile), 65 | createFileSync 66 | } 67 | -------------------------------------------------------------------------------- /handoffs/.clinerules-handoff-manager: -------------------------------------------------------------------------------- 1 | # Handoff Manager Rules 2 | 3 | ## Document Creation Guidelines 4 | 5 | 1. **File Organization**: 6 | - Keep handoff documents ONLY in the handoffs/ root directory 7 | - Follow sequential numbering independent of milestone numbers 8 | - Use descriptive, hyphenated filenames (e.g., 3-database-refactoring.md) 9 | - Reserve 0-prefixed names exclusively for milestone documents 10 | 11 | 2. **Content Quality**: 12 | - Focus on technical specificity rather than general descriptions 13 | - Document unexpected discoveries and non-obvious solutions 14 | - Include relevant code examples with proper formatting 15 | - Maintain a balance between conciseness and completeness 16 | - Prioritize information valuable for future team members 17 | 18 | 3. **Structural Integrity**: 19 | - Maintain consistent section formatting across all handoffs 20 | - Ensure complete coverage of all required sections 21 | - Use appropriate priority levels in the PDR section 22 | - Track work-in-progress with realistic completion percentages 23 | - Document technical deviations with clear rationales 24 | 25 | ## Process Integration 26 | 27 | 1. **Prompt Template Usage**: 28 | - Utilize the CH-create-handoff.md template for consistent creation 29 | - Reference RH-resume-handoff.md when continuing from handoffs 30 | - Encourage users to create milestone summaries after 3-5 handoffs 31 | - Direct users to CM-create-milestone.md when appropriate 32 | 33 | 2. **Context Management**: 34 | - Regularly assess context relevance to maintain performance 35 | - Recommend handoff creation at appropriate threshold points 36 | - Consider conversation length, context dilution, and task completion 37 | - Balance frequency of handoffs with meaningful content creation -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/move/move-sync.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const fs = require('graceful-fs') 4 | const path = require('path') 5 | const copySync = require('../copy').copySync 6 | const removeSync = require('../remove').removeSync 7 | const mkdirpSync = require('../mkdirs').mkdirpSync 8 | const stat = require('../util/stat') 9 | 10 | function moveSync (src, dest, opts) { 11 | opts = opts || {} 12 | const overwrite = opts.overwrite || opts.clobber || false 13 | 14 | const { srcStat, isChangingCase = false } = stat.checkPathsSync(src, dest, 'move', opts) 15 | stat.checkParentPathsSync(src, srcStat, dest, 'move') 16 | if (!isParentRoot(dest)) mkdirpSync(path.dirname(dest)) 17 | return doRename(src, dest, overwrite, isChangingCase) 18 | } 19 | 20 | function isParentRoot (dest) { 21 | const parent = path.dirname(dest) 22 | const parsedPath = path.parse(parent) 23 | return parsedPath.root === parent 24 | } 25 | 26 | function doRename (src, dest, overwrite, isChangingCase) { 27 | if (isChangingCase) return rename(src, dest, overwrite) 28 | if (overwrite) { 29 | removeSync(dest) 30 | return rename(src, dest, overwrite) 31 | } 32 | if (fs.existsSync(dest)) throw new Error('dest already exists.') 33 | return rename(src, dest, overwrite) 34 | } 35 | 36 | function rename (src, dest, overwrite) { 37 | try { 38 | fs.renameSync(src, dest) 39 | } catch (err) { 40 | if (err.code !== 'EXDEV') throw err 41 | return moveAcrossDevice(src, dest, overwrite) 42 | } 43 | } 44 | 45 | function moveAcrossDevice (src, dest, overwrite) { 46 | const opts = { 47 | overwrite, 48 | errorOnExist: true, 49 | preserveTimestamps: true 50 | } 51 | copySync(src, dest, opts) 52 | return removeSync(src) 53 | } 54 | 55 | module.exports = moveSync 56 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/move/move.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const fs = require('../fs') 4 | const path = require('path') 5 | const { copy } = require('../copy') 6 | const { remove } = require('../remove') 7 | const { mkdirp } = require('../mkdirs') 8 | const { pathExists } = require('../path-exists') 9 | const stat = require('../util/stat') 10 | 11 | async function move (src, dest, opts = {}) { 12 | const overwrite = opts.overwrite || opts.clobber || false 13 | 14 | const { srcStat, isChangingCase = false } = await stat.checkPaths(src, dest, 'move', opts) 15 | 16 | await stat.checkParentPaths(src, srcStat, dest, 'move') 17 | 18 | // If the parent of dest is not root, make sure it exists before proceeding 19 | const destParent = path.dirname(dest) 20 | const parsedParentPath = path.parse(destParent) 21 | if (parsedParentPath.root !== destParent) { 22 | await mkdirp(destParent) 23 | } 24 | 25 | return doRename(src, dest, overwrite, isChangingCase) 26 | } 27 | 28 | async function doRename (src, dest, overwrite, isChangingCase) { 29 | if (!isChangingCase) { 30 | if (overwrite) { 31 | await remove(dest) 32 | } else if (await pathExists(dest)) { 33 | throw new Error('dest already exists.') 34 | } 35 | } 36 | 37 | try { 38 | // Try w/ rename first, and try copy + remove if EXDEV 39 | await fs.rename(src, dest) 40 | } catch (err) { 41 | if (err.code !== 'EXDEV') { 42 | throw err 43 | } 44 | await moveAcrossDevice(src, dest, overwrite) 45 | } 46 | } 47 | 48 | async function moveAcrossDevice (src, dest, overwrite) { 49 | const opts = { 50 | overwrite, 51 | errorOnExist: true, 52 | preserveTimestamps: true 53 | } 54 | 55 | await copy(src, dest, opts) 56 | return remove(src) 57 | } 58 | 59 | module.exports = move 60 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/.package-lock.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "handoff-publisher", 3 | "version": "1.0.0", 4 | "lockfileVersion": 3, 5 | "requires": true, 6 | "packages": { 7 | "node_modules/fs-extra": { 8 | "version": "11.3.0", 9 | "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.3.0.tgz", 10 | "integrity": "sha512-Z4XaCL6dUDHfP/jT25jJKMmtxvuwbkrD1vNSMFlo9lNLY2c5FHYSQgHPRZUjAB26TpDEoW9HCOgplrdbaPV/ew==", 11 | "license": "MIT", 12 | "dependencies": { 13 | "graceful-fs": "^4.2.0", 14 | "jsonfile": "^6.0.1", 15 | "universalify": "^2.0.0" 16 | }, 17 | "engines": { 18 | "node": ">=14.14" 19 | } 20 | }, 21 | "node_modules/graceful-fs": { 22 | "version": "4.2.11", 23 | "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz", 24 | "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==", 25 | "license": "ISC" 26 | }, 27 | "node_modules/jsonfile": { 28 | "version": "6.1.0", 29 | "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz", 30 | "integrity": "sha512-5dgndWOriYSm5cnYaJNhalLNDKOqFwyDB/rr1E9ZsGciGvKPs8R2xYGCacuf3z6K1YKDz182fd+fY3cn3pMqXQ==", 31 | "license": "MIT", 32 | "dependencies": { 33 | "universalify": "^2.0.0" 34 | }, 35 | "optionalDependencies": { 36 | "graceful-fs": "^4.1.6" 37 | } 38 | }, 39 | "node_modules/universalify": { 40 | "version": "2.0.1", 41 | "resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.1.tgz", 42 | "integrity": "sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==", 43 | "license": "MIT", 44 | "engines": { 45 | "node": ">= 10.0.0" 46 | } 47 | } 48 | } 49 | } 50 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "fs-extra", 3 | "version": "11.3.0", 4 | "description": "fs-extra contains methods that aren't included in the vanilla Node.js fs package. Such as recursive mkdir, copy, and remove.", 5 | "engines": { 6 | "node": ">=14.14" 7 | }, 8 | "homepage": "https://github.com/jprichardson/node-fs-extra", 9 | "repository": { 10 | "type": "git", 11 | "url": "https://github.com/jprichardson/node-fs-extra" 12 | }, 13 | "keywords": [ 14 | "fs", 15 | "file", 16 | "file system", 17 | "copy", 18 | "directory", 19 | "extra", 20 | "mkdirp", 21 | "mkdir", 22 | "mkdirs", 23 | "recursive", 24 | "json", 25 | "read", 26 | "write", 27 | "extra", 28 | "delete", 29 | "remove", 30 | "touch", 31 | "create", 32 | "text", 33 | "output", 34 | "move", 35 | "promise" 36 | ], 37 | "author": "JP Richardson ", 38 | "license": "MIT", 39 | "dependencies": { 40 | "graceful-fs": "^4.2.0", 41 | "jsonfile": "^6.0.1", 42 | "universalify": "^2.0.0" 43 | }, 44 | "devDependencies": { 45 | "klaw": "^2.1.1", 46 | "klaw-sync": "^3.0.2", 47 | "minimist": "^1.1.1", 48 | "mocha": "^10.1.0", 49 | "nyc": "^15.0.0", 50 | "proxyquire": "^2.0.1", 51 | "read-dir-files": "^0.1.1", 52 | "standard": "^17.0.0" 53 | }, 54 | "main": "./lib/index.js", 55 | "exports": { 56 | ".": "./lib/index.js", 57 | "./esm": "./lib/esm.mjs" 58 | }, 59 | "files": [ 60 | "lib/", 61 | "!lib/**/__tests__/" 62 | ], 63 | "scripts": { 64 | "lint": "standard", 65 | "test-find": "find ./lib/**/__tests__ -name *.test.js | xargs mocha", 66 | "test": "npm run lint && npm run unit && npm run unit-esm", 67 | "unit": "nyc node test.js", 68 | "unit-esm": "node test.mjs" 69 | }, 70 | "sideEffects": false 71 | } 72 | -------------------------------------------------------------------------------- /handoff-system/1-handoff-custom-mode/components/system-prompt-config.json: -------------------------------------------------------------------------------- 1 | { 2 | "components": [ 3 | { 4 | "file": "1-header.md", 5 | "description": "Basic role definition" 6 | }, 7 | { 8 | "file": "2-virtual-tools.md", 9 | "description": "Mandatory virtual tool definitions" 10 | }, 11 | { 12 | "special": "toolEssentials", 13 | "content": "\n\n====\n\nTOOL ESSENTIALS\n\n[Tool essentials section is added from the system]\n\n" 14 | }, 15 | { 16 | "file": "3-directory-detection.md", 17 | "description": "Logic for finding/creating handoff directories" 18 | }, 19 | { 20 | "file": "4-restoration-flowchart.md", 21 | "description": "Visual workflow for session restoration" 22 | }, 23 | { 24 | "file": "5-creation-flowchart.md", 25 | "description": "Visual workflow for handoff/milestone creation" 26 | }, 27 | { 28 | "file": "6-handoff-creation.md", 29 | "description": "Detailed structure and requirements for handoffs" 30 | }, 31 | { 32 | "file": "7-milestone-creation.md", 33 | "description": "Procedures for milestone creation" 34 | }, 35 | { 36 | "file": "8-session-restoration.md", 37 | "description": "Process for restoring context from documents" 38 | }, 39 | { 40 | "file": "9-conversation-extraction.md", 41 | "description": "Integration with conversation analysis" 42 | }, 43 | { 44 | "file": "10-numbering-logic.md", 45 | "description": "Robust sequential numbering procedures" 46 | }, 47 | { 48 | "file": "11-safety-rules.md", 49 | "description": "Error prevention and safety guidelines" 50 | }, 51 | { 52 | "file": "12-workflow-summary.md", 53 | "description": "Mandatory workflow summary at end of prompt" 54 | } 55 | ], 56 | "version": "1.0.0", 57 | "errorHandling": { 58 | "missingFile": "error", 59 | "continueOnError": false 60 | } 61 | } -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/ensure/symlink.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const u = require('universalify').fromPromise 4 | const path = require('path') 5 | const fs = require('../fs') 6 | 7 | const { mkdirs, mkdirsSync } = require('../mkdirs') 8 | 9 | const { symlinkPaths, symlinkPathsSync } = require('./symlink-paths') 10 | const { symlinkType, symlinkTypeSync } = require('./symlink-type') 11 | 12 | const { pathExists } = require('../path-exists') 13 | 14 | const { areIdentical } = require('../util/stat') 15 | 16 | async function createSymlink (srcpath, dstpath, type) { 17 | let stats 18 | try { 19 | stats = await fs.lstat(dstpath) 20 | } catch { } 21 | 22 | if (stats && stats.isSymbolicLink()) { 23 | const [srcStat, dstStat] = await Promise.all([ 24 | fs.stat(srcpath), 25 | fs.stat(dstpath) 26 | ]) 27 | 28 | if (areIdentical(srcStat, dstStat)) return 29 | } 30 | 31 | const relative = await symlinkPaths(srcpath, dstpath) 32 | srcpath = relative.toDst 33 | const toType = await symlinkType(relative.toCwd, type) 34 | const dir = path.dirname(dstpath) 35 | 36 | if (!(await pathExists(dir))) { 37 | await mkdirs(dir) 38 | } 39 | 40 | return fs.symlink(srcpath, dstpath, toType) 41 | } 42 | 43 | function createSymlinkSync (srcpath, dstpath, type) { 44 | let stats 45 | try { 46 | stats = fs.lstatSync(dstpath) 47 | } catch { } 48 | if (stats && stats.isSymbolicLink()) { 49 | const srcStat = fs.statSync(srcpath) 50 | const dstStat = fs.statSync(dstpath) 51 | if (areIdentical(srcStat, dstStat)) return 52 | } 53 | 54 | const relative = symlinkPathsSync(srcpath, dstpath) 55 | srcpath = relative.toDst 56 | type = symlinkTypeSync(relative.toCwd, type) 57 | const dir = path.dirname(dstpath) 58 | const exists = fs.existsSync(dir) 59 | if (exists) return fs.symlinkSync(srcpath, dstpath, type) 60 | mkdirsSync(dir) 61 | return fs.symlinkSync(srcpath, dstpath, type) 62 | } 63 | 64 | module.exports = { 65 | createSymlink: u(createSymlink), 66 | createSymlinkSync 67 | } 68 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/package-lock.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "handoff-publisher", 3 | "version": "1.0.0", 4 | "lockfileVersion": 3, 5 | "requires": true, 6 | "packages": { 7 | "": { 8 | "name": "handoff-publisher", 9 | "version": "1.0.0", 10 | "license": "ISC", 11 | "dependencies": { 12 | "fs-extra": "^11.1.1" 13 | } 14 | }, 15 | "node_modules/fs-extra": { 16 | "version": "11.3.0", 17 | "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.3.0.tgz", 18 | "integrity": "sha512-Z4XaCL6dUDHfP/jT25jJKMmtxvuwbkrD1vNSMFlo9lNLY2c5FHYSQgHPRZUjAB26TpDEoW9HCOgplrdbaPV/ew==", 19 | "license": "MIT", 20 | "dependencies": { 21 | "graceful-fs": "^4.2.0", 22 | "jsonfile": "^6.0.1", 23 | "universalify": "^2.0.0" 24 | }, 25 | "engines": { 26 | "node": ">=14.14" 27 | } 28 | }, 29 | "node_modules/graceful-fs": { 30 | "version": "4.2.11", 31 | "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz", 32 | "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==", 33 | "license": "ISC" 34 | }, 35 | "node_modules/jsonfile": { 36 | "version": "6.1.0", 37 | "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz", 38 | "integrity": "sha512-5dgndWOriYSm5cnYaJNhalLNDKOqFwyDB/rr1E9ZsGciGvKPs8R2xYGCacuf3z6K1YKDz182fd+fY3cn3pMqXQ==", 39 | "license": "MIT", 40 | "dependencies": { 41 | "universalify": "^2.0.0" 42 | }, 43 | "optionalDependencies": { 44 | "graceful-fs": "^4.1.6" 45 | } 46 | }, 47 | "node_modules/universalify": { 48 | "version": "2.0.1", 49 | "resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.1.tgz", 50 | "integrity": "sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==", 51 | "license": "MIT", 52 | "engines": { 53 | "node": ">= 10.0.0" 54 | } 55 | } 56 | } 57 | } 58 | -------------------------------------------------------------------------------- /handoff-system/1-handoff-custom-mode/components/3-directory-detection.md: -------------------------------------------------------------------------------- 1 | ==== 2 | 3 | # Directory Detection 4 | 5 | ## Finding Handoff Directories 6 | 7 | When interacting with the handoff system, you must first locate the existing handoff directory structure or determine where to create it: 8 | 9 | ### Search Priority 10 | 11 | | Order | Location to Check | Notes | 12 | |-------|-------------------|-------| 13 | | 1 | handoffs/ in project root | Most common location | 14 | | 2 | docs/handoffs/ | Common for documentation-heavy projects | 15 | | 3 | documentation/handoffs/ | Alternative documentation location | 16 | | 4 | notes/handoffs/ | Used in some projects | 17 | | 5 | wiki/handoffs/ | For wiki-style documentation | 18 | | 6 | Variations (handoff/, hand-offs/) | Check singular/hyphenated variants | 19 | 20 | ### Creation Logic 21 | 22 | - If no handoff directory exists, suggest creating one 23 | - Create in the root by default, or in docs/ if that directory exists 24 | - Maintain consistent directory structure 25 | 26 | ### Directory Structure 27 | 28 | ``` 29 | handoffs/ 30 | ├── 0-system/ # System files (DO NOT MODIFY DIRECTLY) 31 | │ ├── chat-history/ # RESTRICTED - Raw conversation exports 32 | │ ├── scripts/ # Processing and extraction scripts 33 | │ └── instructions/ # System documentation 34 | │ ├── 0-intro.md 35 | │ ├── 1-handoff-instructions.md 36 | │ ├── 2-milestone-instructions.md 37 | │ ├── 3-milestone-scripts.md 38 | │ └── prompts/ # Prompt templates 39 | │ ├── CH-create-handoff.md 40 | │ ├── CM-create-milestone.md 41 | │ └── RS-restore-session.md 42 | ├── 1-setup.md # Regular handoff documents (in root) 43 | ├── 2-implementation.md # Sequential handoff documents 44 | └── 3-feature-milestone/ # Milestone directory 45 | ├── 0-milestone-summary.md 46 | ├── 0-lessons-learned.md 47 | └── ... # Copies of related handoffs 48 | ``` 49 | 50 | > **Important:** Always use the existing directory structure if one is found. Only suggest creating a new structure if nothing exists. -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/lib/src/4-file-writer.js: -------------------------------------------------------------------------------- 1 | /** 2 | * File writing functions for the installer 3 | */ 4 | 5 | const fs = require('fs'); 6 | const path = require('path'); 7 | 8 | /** 9 | * Function to write all files from the FILES object 10 | * @param {string} targetDir - Target directory 11 | * @param {Object} FILES - Files object with decoded content 12 | */ 13 | function writeAllFiles(targetDir, FILES) { 14 | console.log('\nWriting files...'); 15 | 16 | // Track which critical files we've processed 17 | const criticalFiles = { 18 | '.roomodes': false, 19 | '.clinerules': false 20 | }; 21 | 22 | for (const [filePath, content] of Object.entries(FILES)) { 23 | try { 24 | // Check if this is a critical file 25 | if (filePath === '.roomodes' || filePath === '.clinerules') { 26 | // Mark as processed but don't write yet - will be handled by config merger 27 | criticalFiles[filePath] = true; 28 | console.log(`- Registered ${filePath} for merging`); 29 | continue; 30 | } 31 | 32 | // Get the full path 33 | const fullPath = path.join(targetDir, filePath); 34 | 35 | // Create directory if it doesn't exist 36 | const dirPath = path.dirname(fullPath); 37 | if (!fs.existsSync(dirPath)) { 38 | fs.mkdirSync(dirPath, { recursive: true }); 39 | } 40 | 41 | // Write the file 42 | fs.writeFileSync(fullPath, content); 43 | console.log(`- Created: ${filePath}`); 44 | } catch (err) { 45 | console.error(`- Error writing file ${filePath}: ${err.message}`); 46 | } 47 | } 48 | 49 | // Ensure critical files exist by writing them directly if not found in target directory 50 | for (const [filePath, processed] of Object.entries(criticalFiles)) { 51 | if (processed) { 52 | // We'll let the config merger handle these 53 | continue; 54 | } 55 | 56 | // Critical file was not in FILES 57 | console.warn(`- Warning: ${filePath} not included in installation package`); 58 | } 59 | } 60 | 61 | module.exports = { 62 | writeAllFiles 63 | }; -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/config/publish-config.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "handoff-manager", 3 | "version": "1.1.0", 4 | "description": "Handoff Manager Installer Configuration", 5 | "outputFile": "../../handoff-manager/single-script/handoff-manager-installer.js", 6 | "sourceDir": "../", 7 | "rootFiles": [ 8 | { 9 | "source": "1-handoff-custom-mode/.clinerules", 10 | "target": "single-script/.clinerules" 11 | }, 12 | { 13 | "source": "1-handoff-custom-mode/.roomodes", 14 | "target": "single-script/.roomodes" 15 | }, 16 | { 17 | "source": "handoff-installer-readme.md", 18 | "target": "single-script/handoff-installer-readme.md" 19 | } 20 | ], 21 | "directories": [ 22 | { 23 | "source": "0-instructions", 24 | "target": "handoffs/0-system/instructions", 25 | "backup": true 26 | }, 27 | { 28 | "source": "2-scripts", 29 | "target": "handoffs/0-system/scripts", 30 | "backup": true 31 | }, 32 | { 33 | "source": "chat-history-template", 34 | "target": "handoffs/0-system/chat-history", 35 | "backup": true, 36 | "createIfMissing": true 37 | } 38 | ], 39 | "componentSets": [ 40 | { 41 | "type": "system-prompt", 42 | "sourcePath": "../1-handoff-custom-mode/components", 43 | "configFile": "system-prompt-config.json" 44 | }, 45 | { 46 | "type": "source-code", 47 | "sourcePath": "../handoff-publisher/lib/src", 48 | "configFile": "src-config.json" 49 | } 50 | ], 51 | "maxFileSize": 5242880, 52 | "installOptions": { 53 | "mergeRoomodes": true, 54 | "mergeClinerules": true, 55 | "createBackups": true, 56 | "executable": true 57 | }, 58 | "nextSteps": [ 59 | "Switch to handoff-manager mode in Roo-Code", 60 | "Create your first handoff:", 61 | "I need to create a handoff document for our current work. Please follow the handoff creation workflow." 62 | ], 63 | "documentation": [ 64 | "handoffs/0-instructions/0-intro.md", 65 | "handoffs/0-instructions/1-handoff-instructions.md", 66 | "handoffs/0-instructions/2-milestone-instructions.md" 67 | ] 68 | } -------------------------------------------------------------------------------- /handoff-system/chat-history-template/README.md: -------------------------------------------------------------------------------- 1 | # Conversation History Directory 2 | 3 | ## ⚠️ IMPORTANT: DO NOT DIRECTLY READ FILES FROM THIS DIRECTORY 4 | 5 | This directory is a restricted area designed for raw conversation exports that are too large for direct LLM processing. 6 | 7 | ## How To Use (For Users) 8 | 9 | 1. **Export your conversation** from Roo-Code or other LLM tools 10 | 2. **Place the exported file** in this directory only 11 | 3. **Ask the Handoff Manager** to process it with one of these prompts: 12 | ``` 13 | I saved a conversation export in the chat-history directory. Please process it. 14 | ``` 15 | or 16 | ``` 17 | I need to create a handoff that incorporates my conversation history. 18 | ``` 19 | 20 | ## What Happens (Automated Process) 21 | 22 | 1. The LLM will **check this directory using shell commands** (without reading files) 23 | 2. If files are found, the LLM will **automatically run extraction scripts** 24 | 3. The scripts will **process and clean** the conversation, removing technical details 25 | 4. A **clean extract** will be created in the main handoffs directory 26 | 5. The **original file will be deleted** after successful processing 27 | 6. The LLM will then **analyze the cleaned file** and use it to create a handoff 28 | 29 | ## Important Technical Notes 30 | 31 | - **Files in this directory CANNOT be read directly by the LLM** (by design) 32 | - **DO NOT modify files** in this directory directly 33 | - The LLM should **ONLY use shell commands** to detect files here 34 | - Only the **extraction script should manipulate** these files 35 | - The LLM has **no access to read these files** due to safety restrictions 36 | 37 | ## Safety Features 38 | 39 | - **Access Restriction**: The LLM is prevented from reading files here via regex patterns 40 | - **Shell Commands Only**: Only file existence checks are allowed, not content checks 41 | - **Automated Cleanup**: Original files are deleted after successful extraction 42 | - **Size Warning**: Large files are marked with warning indicators during processing 43 | 44 | This safety system prevents context overflow while still enabling conversation insights to be incorporated into handoff documents. -------------------------------------------------------------------------------- /handoff-manager/handoffs/0-system/chat-history/README.md: -------------------------------------------------------------------------------- 1 | # Conversation History Directory 2 | 3 | ## ⚠️ IMPORTANT: DO NOT DIRECTLY READ FILES FROM THIS DIRECTORY 4 | 5 | This directory is a restricted area designed for raw conversation exports that are too large for direct LLM processing. 6 | 7 | ## How To Use (For Users) 8 | 9 | 1. **Export your conversation** from Roo-Code or other LLM tools 10 | 2. **Place the exported file** in this directory only 11 | 3. **Ask the Handoff Manager** to process it with one of these prompts: 12 | ``` 13 | I saved a conversation export in the chat-history directory. Please process it. 14 | ``` 15 | or 16 | ``` 17 | I need to create a handoff that incorporates my conversation history. 18 | ``` 19 | 20 | ## What Happens (Automated Process) 21 | 22 | 1. The LLM will **check this directory using shell commands** (without reading files) 23 | 2. If files are found, the LLM will **automatically run extraction scripts** 24 | 3. The scripts will **process and clean** the conversation, removing technical details 25 | 4. A **clean extract** will be created in the main handoffs directory 26 | 5. The **original file will be deleted** after successful processing 27 | 6. The LLM will then **analyze the cleaned file** and use it to create a handoff 28 | 29 | ## Important Technical Notes 30 | 31 | - **Files in this directory CANNOT be read directly by the LLM** (by design) 32 | - **DO NOT modify files** in this directory directly 33 | - The LLM should **ONLY use shell commands** to detect files here 34 | - Only the **extraction script should manipulate** these files 35 | - The LLM has **no access to read these files** due to safety restrictions 36 | 37 | ## Safety Features 38 | 39 | - **Access Restriction**: The LLM is prevented from reading files here via regex patterns 40 | - **Shell Commands Only**: Only file existence checks are allowed, not content checks 41 | - **Automated Cleanup**: Original files are deleted after successful extraction 42 | - **Size Warning**: Large files are marked with warning indicators during processing 43 | 44 | This safety system prevents context overflow while still enabling conversation insights to be incorporated into handoff documents. -------------------------------------------------------------------------------- /handoff-system/2-scripts/2-create-milestone.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | """ 3 | Milestone Creation Script (Python) 4 | Creates a new milestone directory and moves handoff files 5 | """ 6 | 7 | import os 8 | import re 9 | import shutil 10 | import sys 11 | 12 | def create_milestone(milestone_name=None): 13 | """Create a milestone directory and move handoff files to it.""" 14 | # Get the next milestone number 15 | milestone_dirs = [d for d in os.listdir("handoffs") 16 | if os.path.isdir(os.path.join("handoffs", d)) 17 | and re.match(r"\d+-", d)] 18 | 19 | if not milestone_dirs: 20 | next_num = 1 # Start with 1 if no milestone directories exist 21 | else: 22 | # Extract numbers from directory names and find the highest 23 | max_num = max([int(re.match(r"(\d+)-", d).group(1)) for d in milestone_dirs]) 24 | next_num = max_num + 1 25 | 26 | # Prompt for milestone name if not provided 27 | if milestone_name is None: 28 | milestone_name = input("Enter milestone name: ") 29 | 30 | # Create milestone directory 31 | milestone_dir = f"handoffs/{next_num}-{milestone_name}" 32 | os.makedirs(milestone_dir, exist_ok=True) 33 | print(f"Created milestone directory: {milestone_dir}") 34 | 35 | # Move handoff files 36 | handoff_files = [f for f in os.listdir("handoffs") 37 | if re.match(r"[1-9]", f) and f.endswith(".md") 38 | and os.path.isfile(os.path.join("handoffs", f))] 39 | 40 | for file in handoff_files: 41 | src = os.path.join("handoffs", file) 42 | dst = os.path.join(milestone_dir, file) 43 | shutil.move(src, dst) 44 | 45 | print(f"Moved {len(handoff_files)} handoff files to milestone directory") 46 | print(f"Milestone {next_num}-{milestone_name} created successfully.") 47 | print("Don't forget to create 0-milestone-summary.md and 0-lessons-learned.md files in the milestone directory.") 48 | 49 | if __name__ == "__main__": 50 | # Get milestone name from command line argument if provided 51 | if len(sys.argv) > 1: 52 | create_milestone(sys.argv[1]) 53 | else: 54 | create_milestone() -------------------------------------------------------------------------------- /handoff-manager/handoffs/0-system/scripts/2-create-milestone.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | """ 3 | Milestone Creation Script (Python) 4 | Creates a new milestone directory and moves handoff files 5 | """ 6 | 7 | import os 8 | import re 9 | import shutil 10 | import sys 11 | 12 | def create_milestone(milestone_name=None): 13 | """Create a milestone directory and move handoff files to it.""" 14 | # Get the next milestone number 15 | milestone_dirs = [d for d in os.listdir("handoffs") 16 | if os.path.isdir(os.path.join("handoffs", d)) 17 | and re.match(r"\d+-", d)] 18 | 19 | if not milestone_dirs: 20 | next_num = 1 # Start with 1 if no milestone directories exist 21 | else: 22 | # Extract numbers from directory names and find the highest 23 | max_num = max([int(re.match(r"(\d+)-", d).group(1)) for d in milestone_dirs]) 24 | next_num = max_num + 1 25 | 26 | # Prompt for milestone name if not provided 27 | if milestone_name is None: 28 | milestone_name = input("Enter milestone name: ") 29 | 30 | # Create milestone directory 31 | milestone_dir = f"handoffs/{next_num}-{milestone_name}" 32 | os.makedirs(milestone_dir, exist_ok=True) 33 | print(f"Created milestone directory: {milestone_dir}") 34 | 35 | # Move handoff files 36 | handoff_files = [f for f in os.listdir("handoffs") 37 | if re.match(r"[1-9]", f) and f.endswith(".md") 38 | and os.path.isfile(os.path.join("handoffs", f))] 39 | 40 | for file in handoff_files: 41 | src = os.path.join("handoffs", file) 42 | dst = os.path.join(milestone_dir, file) 43 | shutil.move(src, dst) 44 | 45 | print(f"Moved {len(handoff_files)} handoff files to milestone directory") 46 | print(f"Milestone {next_num}-{milestone_name} created successfully.") 47 | print("Don't forget to create 0-milestone-summary.md and 0-lessons-learned.md files in the milestone directory.") 48 | 49 | if __name__ == "__main__": 50 | # Get milestone name from command line argument if provided 51 | if len(sys.argv) > 1: 52 | create_milestone(sys.argv[1]) 53 | else: 54 | create_milestone() -------------------------------------------------------------------------------- /handoff-system/README.md: -------------------------------------------------------------------------------- 1 | # Handoff System 2 | 3 | This directory contains the Handoff Manager system and its publisher. 4 | 5 | ## Overview 6 | 7 | The Handoff Manager is a system for creating and managing handoffs between developers. It includes: 8 | 9 | - Custom modes for Roo-Code 10 | - System prompts for handoff management 11 | - Scripts for handoff creation and milestone management 12 | - Documentation for users 13 | 14 | ## Directory Structure 15 | 16 | ``` 17 | handoff-system/ 18 | ├── 0-instructions/ # Documentation for the handoff system 19 | ├── 1-handoff-custom-mode/ # Custom mode for Roo-Code 20 | │ └── components/ # System prompt components 21 | ├── 2-scripts/ # Utility scripts for handoff management 22 | ├── handoff-publisher/ # Package for generating the installer 23 | ├── handoff-installer-readme.md # Readme for the installer 24 | ├── publish.js # Script to run the publisher 25 | └── publish-config.json # Configuration for the publisher 26 | ``` 27 | 28 | ## Publishing the Handoff Manager 29 | 30 | To generate the Handoff Manager installer: 31 | 32 | ```bash 33 | # From the handoff-system directory 34 | node publish-handoff-manager.js 35 | ``` 36 | 37 | This will: 38 | 1. Assemble the system prompt from components 39 | 2. Process all files specified in the configuration 40 | 3. Generate a standalone installer script 41 | 4. Copy the readme file to the output directory 42 | 43 | The installer will be created at the path specified in `publish-config.json`. 44 | 45 | ## Modifying the Handoff System 46 | 47 | To modify the handoff system: 48 | 49 | 1. Edit the files in the appropriate directories 50 | 2. Update the `publish-config.json` if necessary 51 | 3. Run `node publish.js` to generate a new installer 52 | 53 | ## Handoff Publisher Package 54 | 55 | The `handoff-publisher` directory contains a modular package for generating the installer. It has been refactored to improve maintainability and robustness. 56 | 57 | Key features: 58 | - Modular architecture with separate components 59 | - Improved file handling and error recovery 60 | - Better handling of existing configuration files 61 | - Detailed logging for troubleshooting 62 | 63 | See the README.md in the handoff-publisher directory for more details. -------------------------------------------------------------------------------- /handoff-manager/docs/index.md: -------------------------------------------------------------------------------- 1 | # Handoff System Documentation 2 | 3 | ## Introduction 4 | 5 | Welcome to the Handoff System documentation. This suite of documents provides comprehensive information about the Handoff System, its installation, usage, and technical details. 6 | 7 | ## Table of Contents 8 | 9 | | Document | Description | 10 | |----------|-------------| 11 | | [Handoff System Overview](handoff-system.md) | Core concepts, benefits, and architecture of the Handoff System | 12 | | [Basic Installation Guide](basic-installation.md) | Step-by-step guide for automated installation using the installer script | 13 | | [Advanced Installation Guide](advanced-installation.md) | Manual installation process with customization options | 14 | | [Usage Guide](usage-guide.md) | Instructions for using the Handoff Manager after installation | 15 | 16 | ## Quick Start 17 | 18 | For most users, the quickest way to get started is: 19 | 20 | 1. Read the [Handoff System Overview](handoff-system.md) to understand the concepts 21 | 2. Follow the [Basic Installation Guide](basic-installation.md) to install the system 22 | 3. Refer to the [Usage Guide](usage-guide.md) to begin creating handoffs and milestones 23 | 24 | ## System Architecture 25 | 26 | The Handoff System consists of these core components: 27 | 28 | ```mermaid 29 | graph TD 30 | A[Handoff Manager
Custom Mode] --> B[Handoff Documents] 31 | A --> C[Milestone Documents] 32 | A --> D[Session Restoration] 33 | 34 | E[Installer Script] --> F[Configuration Files] 35 | E --> G[Directory Structure] 36 | E --> H[Documentation] 37 | E --> I[Utility Scripts] 38 | 39 | B --> C 40 | C --> D 41 | D --> B 42 | ``` 43 | 44 | ## Developer Paths 45 | 46 | Depending on your needs, you may follow different paths through this documentation: 47 | 48 | ### End User Path 49 | - Handoff System Overview → Basic Installation → Usage Guide 50 | 51 | ### Custom Integration Path 52 | - Handoff System Overview → Advanced Installation → Usage Guide 53 | 54 | ## Additional Resources 55 | 56 | For related topics, refer to: 57 | 58 | - Custom Modes Documentation (in your project's documentation) 59 | - Roo-Code Context Management Documentation 60 | - Node.js Documentation (for script execution) 61 | - Publisher System Documentation (in handoff-publisher/docs directory) -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/jsonfile/index.js: -------------------------------------------------------------------------------- 1 | let _fs 2 | try { 3 | _fs = require('graceful-fs') 4 | } catch (_) { 5 | _fs = require('fs') 6 | } 7 | const universalify = require('universalify') 8 | const { stringify, stripBom } = require('./utils') 9 | 10 | async function _readFile (file, options = {}) { 11 | if (typeof options === 'string') { 12 | options = { encoding: options } 13 | } 14 | 15 | const fs = options.fs || _fs 16 | 17 | const shouldThrow = 'throws' in options ? options.throws : true 18 | 19 | let data = await universalify.fromCallback(fs.readFile)(file, options) 20 | 21 | data = stripBom(data) 22 | 23 | let obj 24 | try { 25 | obj = JSON.parse(data, options ? options.reviver : null) 26 | } catch (err) { 27 | if (shouldThrow) { 28 | err.message = `${file}: ${err.message}` 29 | throw err 30 | } else { 31 | return null 32 | } 33 | } 34 | 35 | return obj 36 | } 37 | 38 | const readFile = universalify.fromPromise(_readFile) 39 | 40 | function readFileSync (file, options = {}) { 41 | if (typeof options === 'string') { 42 | options = { encoding: options } 43 | } 44 | 45 | const fs = options.fs || _fs 46 | 47 | const shouldThrow = 'throws' in options ? options.throws : true 48 | 49 | try { 50 | let content = fs.readFileSync(file, options) 51 | content = stripBom(content) 52 | return JSON.parse(content, options.reviver) 53 | } catch (err) { 54 | if (shouldThrow) { 55 | err.message = `${file}: ${err.message}` 56 | throw err 57 | } else { 58 | return null 59 | } 60 | } 61 | } 62 | 63 | async function _writeFile (file, obj, options = {}) { 64 | const fs = options.fs || _fs 65 | 66 | const str = stringify(obj, options) 67 | 68 | await universalify.fromCallback(fs.writeFile)(file, str, options) 69 | } 70 | 71 | const writeFile = universalify.fromPromise(_writeFile) 72 | 73 | function writeFileSync (file, obj, options = {}) { 74 | const fs = options.fs || _fs 75 | 76 | const str = stringify(obj, options) 77 | // not sure if fs.writeFileSync returns anything, but just in case 78 | return fs.writeFileSync(file, str, options) 79 | } 80 | 81 | const jsonfile = { 82 | readFile, 83 | readFileSync, 84 | writeFile, 85 | writeFileSync 86 | } 87 | 88 | module.exports = jsonfile 89 | -------------------------------------------------------------------------------- /roomodes-validator/README.md: -------------------------------------------------------------------------------- 1 | # Roo Modes Validator 2 | 3 | A validation tool for checking `.roomodes` files in Roo-Code projects. 4 | 5 | ## Overview 6 | 7 | This script validates `.roomodes` configuration files for correct formatting and content according to the Roo-Code specifications. It can identify common issues and optionally fix them automatically. 8 | 9 | ## Usage 10 | 11 | ```bash 12 | node validate-roomodes.js [options] [path] 13 | ``` 14 | 15 | ## Options 16 | 17 | - `-h, --help`: Show help message 18 | - `-f, --fix`: Generate a fixed version of the file 19 | - `-o, --output PATH`: Specify output path for fixed file (default: ./.roomodes-fixed) 20 | 21 | ## Examples 22 | 23 | ```bash 24 | # Validate .roomodes in current directory 25 | node validate-roomodes.js 26 | 27 | # Validate a specific file 28 | node validate-roomodes.js ./path/to/.roomodes 29 | 30 | # Fix a file and save to default path (.roomodes-fixed) 31 | node validate-roomodes.js --fix 32 | 33 | # Fix a file and save to custom path 34 | node validate-roomodes.js --fix --output ./fixed.roomodes 35 | ``` 36 | 37 | ## Validation Rules 38 | 39 | The validator checks for these issues: 40 | 41 | ### Structure Issues 42 | - Missing or invalid "customModes" array (proper key name) 43 | - Empty customModes array 44 | 45 | ### Mode Validation 46 | - **Slug**: Must be present, unique, and contain only lowercase letters, numbers, and hyphens 47 | - **Name**: Must be present 48 | - **RoleDefinition**: Must be present and be a string (warns if it doesn't start with "You are Roo") 49 | - **Groups**: Must be an array containing valid tool groups 50 | 51 | ### Group Validation 52 | - Must be one of the valid tool groups: `read`, `edit`, `browser`, `command`, `mcp` 53 | - File restrictions must have valid `fileRegex` and `description` properties 54 | - Regex patterns must be properly escaped for JSON context 55 | 56 | ## Auto-fix Capabilities 57 | 58 | When run with the `--fix` flag, the script can correct: 59 | 60 | - Rename `modes` key to `customModes` if needed 61 | - Fix invalid slug formats 62 | - Add missing required fields with sensible defaults 63 | - Fix invalid group definitions 64 | - Correct regex escaping in file restriction patterns 65 | - Ensure unique slugs by adding suffixes when needed 66 | 67 | ## Exit Codes 68 | 69 | - `0`: Validation successful (no errors) 70 | - `1`: Validation failed (errors found) -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/universalify/README.md: -------------------------------------------------------------------------------- 1 | # universalify 2 | 3 | ![GitHub Workflow Status (branch)](https://img.shields.io/github/actions/workflow/status/RyanZim/universalify/ci.yml?branch=master) 4 | ![Coveralls github branch](https://img.shields.io/coveralls/github/RyanZim/universalify/master.svg) 5 | ![npm](https://img.shields.io/npm/dm/universalify.svg) 6 | ![npm](https://img.shields.io/npm/l/universalify.svg) 7 | 8 | Make a callback- or promise-based function support both promises and callbacks. 9 | 10 | Uses the native promise implementation. 11 | 12 | ## Installation 13 | 14 | ```bash 15 | npm install universalify 16 | ``` 17 | 18 | ## API 19 | 20 | ### `universalify.fromCallback(fn)` 21 | 22 | Takes a callback-based function to universalify, and returns the universalified function. 23 | 24 | Function must take a callback as the last parameter that will be called with the signature `(error, result)`. `universalify` does not support calling the callback with three or more arguments, and does not ensure that the callback is only called once. 25 | 26 | ```js 27 | function callbackFn (n, cb) { 28 | setTimeout(() => cb(null, n), 15) 29 | } 30 | 31 | const fn = universalify.fromCallback(callbackFn) 32 | 33 | // Works with Promises: 34 | fn('Hello World!') 35 | .then(result => console.log(result)) // -> Hello World! 36 | .catch(error => console.error(error)) 37 | 38 | // Works with Callbacks: 39 | fn('Hi!', (error, result) => { 40 | if (error) return console.error(error) 41 | console.log(result) 42 | // -> Hi! 43 | }) 44 | ``` 45 | 46 | ### `universalify.fromPromise(fn)` 47 | 48 | Takes a promise-based function to universalify, and returns the universalified function. 49 | 50 | Function must return a valid JS promise. `universalify` does not ensure that a valid promise is returned. 51 | 52 | ```js 53 | function promiseFn (n) { 54 | return new Promise(resolve => { 55 | setTimeout(() => resolve(n), 15) 56 | }) 57 | } 58 | 59 | const fn = universalify.fromPromise(promiseFn) 60 | 61 | // Works with Promises: 62 | fn('Hello World!') 63 | .then(result => console.log(result)) // -> Hello World! 64 | .catch(error => console.error(error)) 65 | 66 | // Works with Callbacks: 67 | fn('Hi!', (error, result) => { 68 | if (error) return console.error(error) 69 | console.log(result) 70 | // -> Hi! 71 | }) 72 | ``` 73 | 74 | ## License 75 | 76 | MIT 77 | -------------------------------------------------------------------------------- /handoffs/0-instructions/3-milestone-scripts.md: -------------------------------------------------------------------------------- 1 | # Milestone Reorganization Functions 2 | 3 | These one-liner functions create a new milestone folder within handoffs/ and move all numbered handoff files into it. 4 | 5 | ## Bash 6 | ```bash 7 | next_num=$(find handoffs/ -maxdepth 1 -type d -name "[0-9]*-*" 2>/dev/null | wc -l | xargs test "0" -eq && echo "1" || find handoffs/ -maxdepth 1 -type d -name "[0-9]*-*" | sort -V | tail -n1 | sed -E 's/.*\/([0-9]+).*/\1/' | awk '{print $1+1}'); mkdir -p "handoffs/${next_num}-milestone-name"; find handoffs/ -maxdepth 1 -type f -name "[1-9]*.md" -exec mv {} "handoffs/${next_num}-milestone-name/" \; 8 | ``` 9 | 10 | ## PowerShell 11 | ```powershell 12 | $next_num = if (!(Get-ChildItem "handoffs" -Directory | Where {$_.Name -match "^\d+-"})) {1} else {(Get-ChildItem "handoffs" -Directory | Where {$_.Name -match "^\d+-"} | ForEach {[int]($_.Name -split "-")[0]} | Measure -Max).Maximum + 1}; New-Item -Path "handoffs/${next_num}-milestone-name" -ItemType Directory -Force; Get-ChildItem -Path "handoffs" -Filter "[1-9]*.md" | Move-Item -Destination "handoffs/${next_num}-milestone-name/" 13 | ``` 14 | 15 | ## Python 16 | ```python 17 | import os, re, shutil; next_num = 1 if not [d for d in os.listdir("handoffs") if os.path.isdir(os.path.join("handoffs", d)) and re.match(r"\d+-", d)] else max([int(re.match(r"(\d+)-", d).group(1)) for d in os.listdir("handoffs") if os.path.isdir(os.path.join("handoffs", d)) and re.match(r"\d+-", d)]) + 1; os.makedirs(f"handoffs/{next_num}-milestone-name", exist_ok=True); [shutil.move(os.path.join("handoffs", f), os.path.join(f"handoffs/{next_num}-milestone-name", f)) for f in os.listdir("handoffs") if re.match(r"[1-9]", f) and f.endswith(".md") and os.path.isfile(os.path.join("handoffs", f))] 18 | ``` 19 | 20 | ## Node.js 21 | ```javascript 22 | const fs = require('fs'), path = require('path'); const dirs = fs.readdirSync('handoffs').filter(d => fs.statSync(path.join('handoffs', d)).isDirectory() && /^\d+-/.test(d)); const next_num = dirs.length === 0 ? 1 : Math.max(...dirs.map(d => parseInt(d.match(/^(\d+)-/)[1]) || 0)) + 1; fs.mkdirSync(path.join('handoffs', `${next_num}-milestone-name`), { recursive: true }); fs.readdirSync('handoffs').filter(f => /^[1-9].*\.md$/.test(f) && fs.statSync(path.join('handoffs', f)).isFile()).forEach(f => fs.renameSync(path.join('handoffs', f), path.join('handoffs', `${next_num}-milestone-name`, f))); 23 | ``` 24 | 25 | Replace "milestone-name" with the actual milestone name before executing. -------------------------------------------------------------------------------- /handoff-system/0-instructions/3-milestone-scripts.md: -------------------------------------------------------------------------------- 1 | # Milestone Reorganization Functions 2 | 3 | These one-liner functions create a new milestone folder within handoffs/ and move all numbered handoff files into it. 4 | 5 | ## Bash 6 | ```bash 7 | next_num=$(find handoffs/ -maxdepth 1 -type d -name "[0-9]*-*" 2>/dev/null | wc -l | xargs test "0" -eq && echo "1" || find handoffs/ -maxdepth 1 -type d -name "[0-9]*-*" | sort -V | tail -n1 | sed -E 's/.*\/([0-9]+).*/\1/' | awk '{print $1+1}'); mkdir -p "handoffs/${next_num}-milestone-name"; find handoffs/ -maxdepth 1 -type f -name "[1-9]*.md" -exec mv {} "handoffs/${next_num}-milestone-name/" \; 8 | ``` 9 | 10 | ## PowerShell 11 | ```powershell 12 | $next_num = if (!(Get-ChildItem "handoffs" -Directory | Where {$_.Name -match "^\d+-"})) {1} else {(Get-ChildItem "handoffs" -Directory | Where {$_.Name -match "^\d+-"} | ForEach {[int]($_.Name -split "-")[0]} | Measure -Max).Maximum + 1}; New-Item -Path "handoffs/${next_num}-milestone-name" -ItemType Directory -Force; Get-ChildItem -Path "handoffs" -Filter "[1-9]*.md" | Move-Item -Destination "handoffs/${next_num}-milestone-name/" 13 | ``` 14 | 15 | ## Python 16 | ```python 17 | import os, re, shutil; next_num = 1 if not [d for d in os.listdir("handoffs") if os.path.isdir(os.path.join("handoffs", d)) and re.match(r"\d+-", d)] else max([int(re.match(r"(\d+)-", d).group(1)) for d in os.listdir("handoffs") if os.path.isdir(os.path.join("handoffs", d)) and re.match(r"\d+-", d)]) + 1; os.makedirs(f"handoffs/{next_num}-milestone-name", exist_ok=True); [shutil.move(os.path.join("handoffs", f), os.path.join(f"handoffs/{next_num}-milestone-name", f)) for f in os.listdir("handoffs") if re.match(r"[1-9]", f) and f.endswith(".md") and os.path.isfile(os.path.join("handoffs", f))] 18 | ``` 19 | 20 | ## Node.js 21 | ```javascript 22 | const fs = require('fs'), path = require('path'); const dirs = fs.readdirSync('handoffs').filter(d => fs.statSync(path.join('handoffs', d)).isDirectory() && /^\d+-/.test(d)); const next_num = dirs.length === 0 ? 1 : Math.max(...dirs.map(d => parseInt(d.match(/^(\d+)-/)[1]) || 0)) + 1; fs.mkdirSync(path.join('handoffs', `${next_num}-milestone-name`), { recursive: true }); fs.readdirSync('handoffs').filter(f => /^[1-9].*\.md$/.test(f) && fs.statSync(path.join('handoffs', f)).isFile()).forEach(f => fs.renameSync(path.join('handoffs', f), path.join('handoffs', `${next_num}-milestone-name`, f))); 23 | ``` 24 | 25 | Replace "milestone-name" with the actual milestone name before executing. -------------------------------------------------------------------------------- /handoff-system/1-handoff-custom-mode/components/6-handoff-creation.md: -------------------------------------------------------------------------------- 1 | 2 | ==== 3 | 4 | # Handoff Document Creation 5 | 6 | ## Template Structure 7 | 8 | Every handoff document should follow this structure: 9 | 10 | ```markdown 11 | # [TOPIC] Handoff - [DATE] 12 | 13 | ## Summary 14 | [2-3 sentence overview] 15 | 16 | ## Priority Development Requirements (PDR) 17 | - **HIGH**: [Must address immediately] 18 | - **MEDIUM**: [Address soon] 19 | - **LOW**: [Be aware] 20 | 21 | ## Discoveries 22 | - [Unexpected finding 1] 23 | - [Unexpected finding 2] 24 | 25 | ## Problems & Solutions 26 | - **Problem**: [Issue description] 27 | **Solution**: [Solution applied] 28 | ```code example if needed``` 29 | 30 | ## Work in Progress 31 | - [Task 1]: [Progress %] 32 | - [Task 2]: [Progress %] 33 | 34 | ## Deviations 35 | - [Changed X to Y because Z] 36 | 37 | ## References 38 | - [doc/path1] 39 | - [doc/path2] 40 | ``` 41 | 42 | ## Required Content 43 | 44 | Every handoff must include: 45 | 46 | | Section | Description | Purpose | 47 | |---------|-------------|---------| 48 | | **Date** | Current date at document top | Chronological reference | 49 | | **Summary** | Brief overview of accomplishments and status | Quick context | 50 | | **PDR** | Prioritized items needing attention (HIGH/MEDIUM/LOW) | Focus attention | 51 | | **Discoveries** | Unexpected findings and insights | Share knowledge | 52 | | **Problems & Solutions** | Each problem paired with its solution | Prevent repeating work | 53 | | **Work in Progress** | Tasks still being worked on with completion estimates | Continuity | 54 | | **Deviations** | Changes from original plan/approach | Explain decisions | 55 | | **References** | Links to relevant docs, code, previous handoffs | Further reading | 56 | 57 | ## Naming Convention 58 | 59 | Always use sequential numbering for handoff files: 60 | - Format: `N-descriptive-name.md` (e.g., `4-database-refactoring.md`) 61 | - Never use 0-prefix for handoff files (reserved for system files and milestone documents) 62 | - Keep the descriptive name brief but meaningful 63 | - Place handoff documents directly in the handoffs/ root directory (not in the 0-system directory) 64 | 65 | > **Example:** If existing handoffs are 1-setup.md and 2-api-design.md, the next handoff should be 3-[descriptive-name].md 66 | 67 | > **Important:** The 0-system directory is reserved for system files and should not contain handoff documents. All actual handoff documents should be placed in the root of the handoffs directory. -------------------------------------------------------------------------------- /handoff-manager/handoffs/0-system/instructions/3-milestone-scripts.md: -------------------------------------------------------------------------------- 1 | # Milestone Reorganization Functions 2 | 3 | These one-liner functions create a new milestone folder within handoffs/ and move all numbered handoff files into it. 4 | 5 | ## Bash 6 | ```bash 7 | next_num=$(find handoffs/ -maxdepth 1 -type d -name "[0-9]*-*" 2>/dev/null | wc -l | xargs test "0" -eq && echo "1" || find handoffs/ -maxdepth 1 -type d -name "[0-9]*-*" | sort -V | tail -n1 | sed -E 's/.*\/([0-9]+).*/\1/' | awk '{print $1+1}'); mkdir -p "handoffs/${next_num}-milestone-name"; find handoffs/ -maxdepth 1 -type f -name "[1-9]*.md" -exec mv {} "handoffs/${next_num}-milestone-name/" \; 8 | ``` 9 | 10 | ## PowerShell 11 | ```powershell 12 | $next_num = if (!(Get-ChildItem "handoffs" -Directory | Where {$_.Name -match "^\d+-"})) {1} else {(Get-ChildItem "handoffs" -Directory | Where {$_.Name -match "^\d+-"} | ForEach {[int]($_.Name -split "-")[0]} | Measure -Max).Maximum + 1}; New-Item -Path "handoffs/${next_num}-milestone-name" -ItemType Directory -Force; Get-ChildItem -Path "handoffs" -Filter "[1-9]*.md" | Move-Item -Destination "handoffs/${next_num}-milestone-name/" 13 | ``` 14 | 15 | ## Python 16 | ```python 17 | import os, re, shutil; next_num = 1 if not [d for d in os.listdir("handoffs") if os.path.isdir(os.path.join("handoffs", d)) and re.match(r"\d+-", d)] else max([int(re.match(r"(\d+)-", d).group(1)) for d in os.listdir("handoffs") if os.path.isdir(os.path.join("handoffs", d)) and re.match(r"\d+-", d)]) + 1; os.makedirs(f"handoffs/{next_num}-milestone-name", exist_ok=True); [shutil.move(os.path.join("handoffs", f), os.path.join(f"handoffs/{next_num}-milestone-name", f)) for f in os.listdir("handoffs") if re.match(r"[1-9]", f) and f.endswith(".md") and os.path.isfile(os.path.join("handoffs", f))] 18 | ``` 19 | 20 | ## Node.js 21 | ```javascript 22 | const fs = require('fs'), path = require('path'); const dirs = fs.readdirSync('handoffs').filter(d => fs.statSync(path.join('handoffs', d)).isDirectory() && /^\d+-/.test(d)); const next_num = dirs.length === 0 ? 1 : Math.max(...dirs.map(d => parseInt(d.match(/^(\d+)-/)[1]) || 0)) + 1; fs.mkdirSync(path.join('handoffs', `${next_num}-milestone-name`), { recursive: true }); fs.readdirSync('handoffs').filter(f => /^[1-9].*\.md$/.test(f) && fs.statSync(path.join('handoffs', f)).isFile()).forEach(f => fs.renameSync(path.join('handoffs', f), path.join('handoffs', `${next_num}-milestone-name`, f))); 23 | ``` 24 | 25 | Replace "milestone-name" with the actual milestone name before executing. -------------------------------------------------------------------------------- /handoff-system/0-instructions/prompts/CH-create-handoff.md: -------------------------------------------------------------------------------- 1 | # Creating a Handoff Document 2 | 3 | Use this prompt when you need to create a new handoff document to capture your current progress. 4 | 5 | ## Workflow-Guided Prompt 6 | 7 | ``` 8 | I need to create a handoff document for our current work. Please follow the handoff creation workflow. 9 | ``` 10 | 11 | ## Standard Prompt Template 12 | 13 | ``` 14 | I need to create a handoff document for our current work. Please: 15 | 16 | 1. Read the handoffs/0-instructions/1-handoff-instructions.md 17 | (The handoff directory may not be at the project root) 18 | 2. Examine the handoff directory structure to find existing handoffs 19 | 3. Determine the next sequential handoff number using the numbering logic 20 | 4. Check if a conversation extract is available to incorporate 21 | 5. Create a properly structured handoff file with the correct number 22 | ``` 23 | 24 | ## Enhanced Context 25 | 26 | For a more targeted handoff, provide specific context: 27 | 28 | ``` 29 | I need to create a handoff document for our current work. Please: 30 | 31 | 1. Follow the handoff creation workflow 32 | 2. Use today's date and focus on [SPECIFIC TOPIC] 33 | 3. Include these key points in the handoff: 34 | - [KEY POINT 1] 35 | - [KEY POINT 2] 36 | - [KEY POINT 3] 37 | ``` 38 | 39 | ## Conversation Extract Integration 40 | 41 | To include conversation extract analysis: 42 | 43 | ``` 44 | I need to create a handoff document incorporating insights from our conversation. 45 | 46 | 1. Follow the handoff creation workflow 47 | 2. Analyze the provided conversation extract (extracted_conversation.md) 48 | 3. Incorporate relevant insights into the handoff document 49 | ``` 50 | 51 | ## Numbering Logic 52 | 53 | The handoff-manager now uses a robust numbering algorithm: 54 | 55 | 1. List all files in the handoffs/ directory 56 | 2. Filter to only include files matching the pattern `[0-9]+-*.md` 57 | 3. Extract the numeric prefix from each filename 58 | 4. Sort numerically by prefix 59 | 5. Select the highest number and increment 60 | 6. If no existing handoffs, start with 1 61 | 62 | This structured approach significantly improves numbering accuracy. 63 | 64 | ## Best Practices 65 | 66 | - **Be Specific**: Include concrete details and measurable outcomes 67 | - **Focus on Changes**: Emphasize what's different now vs. before 68 | - **Highlight Roadblocks**: Document issues encountered and their solutions 69 | - **Track Progress**: Note completion percentages for in-progress items 70 | - **Reference Related Files**: Link to relevant code or documentation -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/lib/src/5-installer.js: -------------------------------------------------------------------------------- 1 | /** 2 | * Main installer function for the handoff manager 3 | */ 4 | 5 | const fs = require('fs'); 6 | const path = require('path'); 7 | const backup = require('./2-backup'); 8 | const configMerger = require('./3-config-merger'); 9 | const fileWriter = require('./4-file-writer'); 10 | const utils = require('./1-utils'); 11 | 12 | /** 13 | * Main installation function 14 | * @param {string} targetDir - Target directory 15 | * @param {Object} CONFIG - Configuration object 16 | * @param {Object} FILES - Files object with decoded content 17 | * @param {string} version - Version number 18 | * @returns {boolean} - Success status 19 | */ 20 | async function installHandoffManager(targetDir, CONFIG, FILES, version) { 21 | try { 22 | // First backup any existing handoff system 23 | const backupPaths = CONFIG.installOptions.createBackups ? 24 | backup.backupExistingInstallation(targetDir) : {}; 25 | 26 | // Write all files to the target directory 27 | fileWriter.writeAllFiles(targetDir, FILES); 28 | 29 | // Create handoffs directory if it doesn't exist 30 | const targetHandoffsDir = path.join(targetDir, 'handoffs'); 31 | utils.ensureDir(targetHandoffsDir); 32 | 33 | // Merge configuration files if needed 34 | configMerger.processConfigMerging(targetDir, CONFIG, FILES); 35 | 36 | // Display success message and next steps 37 | console.log(` 38 | ╔══════════════════════════════════════════════════╗ 39 | ║ ║ 40 | ║ Handoff Manager Install Complete ║ 41 | ║ ║ 42 | ╚══════════════════════════════════════════════════╝ 43 | 44 | The Handoff Manager (v${version}) has been installed to ${targetDir} 45 | 46 | Files installed: 47 | - Custom mode in .roomodes 48 | - Handoff rules in .clinerules 49 | - System prompt (if applicable) 50 | ${CONFIG.directories.map(dir => `- ${dir.target}`).join('\n')} 51 | ${Object.keys(backupPaths).length > 0 ? ` 52 | Backup created:` : ''} 53 | ${Object.entries(backupPaths).map(([dir, path]) => `- Previous ${dir} preserved in ${path}`).join('\n')} 54 | 55 | Next Steps: 56 | ${CONFIG.nextSteps.map(step => `${step}`).join('\n')} 57 | 58 | For documentation, see: 59 | ${CONFIG.documentation.map(doc => `- ${doc}`).join('\n')}`); 60 | 61 | return true; 62 | } catch (error) { 63 | console.error('Error during installation:', error); 64 | return false; 65 | } 66 | } 67 | 68 | module.exports = { 69 | installHandoffManager 70 | }; -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/docs/publish-workflow.md: -------------------------------------------------------------------------------- 1 | # Handoff Publisher Workflow 2 | 3 | ```mermaid 4 | %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#333', 'primaryTextColor': '#fff', 'lineColor': '#666'}}}%% 5 | flowchart TD 6 | Start([ 1 - Start Publisher Script]) --> ReadConfig[ 2 - Read Configuration Files
config/publish-config.json] 7 | 8 | ReadConfig --> LoadComponents[ 3 - Load Component Sets
system-prompt-config.json, src-config.json] 9 | 10 | LoadComponents --> AssemblePrompt[ 4 - Assemble System Prompt
using system-prompt.js] 11 | 12 | AssemblePrompt --> ProcessRootFiles[ 5 - Process Root Files
using system-prompt.js] 13 | ProcessRootFiles --> ProcessDirectories[ 6 - Process Directories
using installer-assembler.js] 14 | 15 | ProcessDirectories --> AssembleSrc[ 7 - Assemble Source Components
using src-assembler.js] 16 | 17 | AssembleSrc --> GenerateInstaller[ 8 - Generate & Write Installer
using installer-assembler.js] 18 | 19 | GenerateInstaller --> CopyReadme[ 9 - Copy Readme File] 20 | 21 | CopyReadme --> DisplaySuccess[ 10 - Display Success Message] 22 | DisplaySuccess --> End([ 11 - End Publisher Script]) 23 | ``` 24 | 25 | This flowchart represents the high-level operational flow of the modular handoff publisher package. The package: 26 | 27 | 1. Reads configuration from the config directory 28 | 2. Loads component set configurations (system-prompt and source-code) 29 | 3. Assembles the system prompt using the system-prompt module 30 | 4. Processes root files using the system-prompt module 31 | 5. Processes directories using the installer-assembler module 32 | 6. Assembles source code components using the src-assembler module 33 | 7. Generates a self-contained installer using the installer-assembler module 34 | 8. Copies the readme file to the output directory 35 | 9. Displays a success message 36 | 37 | The modular architecture improves maintainability by separating concerns into distinct components: 38 | - `file-utils.js`: File operation utilities 39 | - `config-merger.js`: Handles merging of configuration files 40 | - `system-prompt.js`: Assembles the system prompt 41 | - `src-assembler.js`: Assembles source code components 42 | - `installer-assembler.js`: Generates the installer script 43 | - `index.js`: Main entry point 44 | 45 | The component-based design allows for easy extension through standardized component sets defined in publish-config.json. See [Component Sets Specification](component-sets-specification.md) for details on creating additional component sets. -------------------------------------------------------------------------------- /handoff-manager/handoffs/0-system/instructions/prompts/CH-create-handoff.md: -------------------------------------------------------------------------------- 1 | # Creating a Handoff Document 2 | 3 | Use this prompt when you need to create a new handoff document to capture your current progress. 4 | 5 | ## Workflow-Guided Prompt 6 | 7 | ``` 8 | I need to create a handoff document for our current work. Please follow the handoff creation workflow. 9 | ``` 10 | 11 | ## Standard Prompt Template 12 | 13 | ``` 14 | I need to create a handoff document for our current work. Please: 15 | 16 | 1. Read the handoffs/0-instructions/1-handoff-instructions.md 17 | (The handoff directory may not be at the project root) 18 | 2. Examine the handoff directory structure to find existing handoffs 19 | 3. Determine the next sequential handoff number using the numbering logic 20 | 4. Check if a conversation extract is available to incorporate 21 | 5. Create a properly structured handoff file with the correct number 22 | ``` 23 | 24 | ## Enhanced Context 25 | 26 | For a more targeted handoff, provide specific context: 27 | 28 | ``` 29 | I need to create a handoff document for our current work. Please: 30 | 31 | 1. Follow the handoff creation workflow 32 | 2. Use today's date and focus on [SPECIFIC TOPIC] 33 | 3. Include these key points in the handoff: 34 | - [KEY POINT 1] 35 | - [KEY POINT 2] 36 | - [KEY POINT 3] 37 | ``` 38 | 39 | ## Conversation Extract Integration 40 | 41 | To include conversation extract analysis: 42 | 43 | ``` 44 | I need to create a handoff document incorporating insights from our conversation. 45 | 46 | 1. Follow the handoff creation workflow 47 | 2. Analyze the provided conversation extract (extracted_conversation.md) 48 | 3. Incorporate relevant insights into the handoff document 49 | ``` 50 | 51 | ## Numbering Logic 52 | 53 | The handoff-manager now uses a robust numbering algorithm: 54 | 55 | 1. List all files in the handoffs/ directory 56 | 2. Filter to only include files matching the pattern `[0-9]+-*.md` 57 | 3. Extract the numeric prefix from each filename 58 | 4. Sort numerically by prefix 59 | 5. Select the highest number and increment 60 | 6. If no existing handoffs, start with 1 61 | 62 | This structured approach significantly improves numbering accuracy. 63 | 64 | ## Best Practices 65 | 66 | - **Be Specific**: Include concrete details and measurable outcomes 67 | - **Focus on Changes**: Emphasize what's different now vs. before 68 | - **Highlight Roadblocks**: Document issues encountered and their solutions 69 | - **Track Progress**: Note completion percentages for in-progress items 70 | - **Reference Related Files**: Link to relevant code or documentation -------------------------------------------------------------------------------- /handoffs/0-instructions/prompts/RS-restore-session.md: -------------------------------------------------------------------------------- 1 | # Session Restoration Prompt Template 2 | 3 | When returning to a project after breaks or context resets, use this prompt to efficiently restore context from handoffs and milestones. 4 | 5 | **For best results, you need to customize this prompt!** 6 | 7 | ## Template 8 | 9 | ``` 10 | Before we begin, please: 11 | 12 | 1. Examine the handoffs/ directory structure 13 | 2. Check if handoff documents exist in the root directory 14 | 15 | If handoff documents exist in the root directory: 16 | 17 | A. First review all milestone directories in numerical order 18 | - Read ONLY the 0-prefixed documents in each milestone directory 19 | - Skip any numbered documents within milestone directories 20 | 21 | B. Then read ALL handoff documents in the root directory in numerical order 22 | - Pay special attention to the most recent handoff for current state 23 | 24 | If NO handoff documents exist in the root directory: 25 | 26 | - Review all milestone directories in numerical order 27 | - Read ONLY the 0-prefixed documents in each milestone directory 28 | - Skip any numbered documents within milestone directories 29 | 30 | After reading, please verify your understanding by: 31 | 1. Listing all milestone directories in numerical order 32 | 2. Listing all handoff documents you've read (if any) 33 | 3. Summarizing the current project state and next steps 34 | 35 | This will ensure you have the right context while optimizing token usage. 36 | ``` 37 | 38 | ## Project-Specific Customization 39 | 40 | Add additional project-specific files to read: 41 | 42 | ``` 43 | Additionally, please read these key project files: 44 | - README.md for project overview 45 | - .clinerules for workspace specific guidance 46 | - [specific file paths relevant to your current work] 47 | - [configuration files needed for context] 48 | ``` 49 | 50 | ## Advanced Verification 51 | 52 | For more comprehensive verification: 53 | 54 | ``` 55 | Please verify your understanding more deeply by: 56 | 1. Listing major features completed across all milestones 57 | 2. Identifying recurring patterns or lessons from milestone documents 58 | 3. Summarizing the most important open issues from handoff documents 59 | 4. Explaining the overall project architecture as you understand it 60 | ``` 61 | 62 | ## Session Focus 63 | 64 | To guide the session toward specific goals: 65 | 66 | ``` 67 | After restoring context, please focus on: 68 | - [specific feature or component to work on] 69 | - [particular problem that needs solving] 70 | - [next steps in the project roadmap] -------------------------------------------------------------------------------- /handoff-system/1-handoff-custom-mode/components/10-numbering-logic.md: -------------------------------------------------------------------------------- 1 | 2 | ==== 3 | 4 | # Numbering Logic 5 | 6 | ## Handoff Document Numbering 7 | 8 | To ensure consistent sequential numbering: 9 | 10 | ### Finding the Next Number 11 | 12 | ```mermaid 13 | graph TD 14 | A[Start] --> B[List Files in
handoffs/ Root] 15 | B --> C[Filter for Pattern
[0-9]+-*.md] 16 | C --> D[Extract Numeric
Prefix] 17 | D --> E[Sort Numerically] 18 | E --> F[Find Highest Number] 19 | F --> G[Add 1 to
Highest Number] 20 | G --> H[Use as Next
Handoff Number] 21 | B --> I{No Matching
Files?} 22 | I -->|Yes| J[Start with 1] 23 | J --> H 24 | ``` 25 | 26 | #### Implementation Steps 27 | 28 | 1. List all files in the handoffs/ directory 29 | 2. Filter to only include files matching the pattern `[0-9]+-*.md` 30 | 3. Extract the numeric prefix from each filename 31 | 4. Sort numerically by prefix 32 | 5. Select the highest number and increment 33 | 6. If no existing handoffs, start with 1 34 | 35 | #### Examples 36 | 37 | | Existing Files | Next Number | 38 | |----------------|-------------| 39 | | 1-setup.md, 2-api-design.md | 3 | 40 | | None | 1 | 41 | | 1-setup.md, 3-bugfix.md | 4 | 42 | | 5-feature.md | 6 | 43 | 44 | ## Milestone Directory Numbering 45 | 46 | For milestone directory numbering: 47 | 48 | ### Finding the Next Number 49 | 50 | ```mermaid 51 | graph TD 52 | A[Start] --> B[List Directories in
handoffs/ Root] 53 | B --> C[Filter for Pattern
[0-9]+-*] 54 | C --> D[Extract Numeric
Prefix] 55 | D --> E[Sort Numerically] 56 | E --> F[Find Highest Number] 57 | F --> G[Add 1 to
Highest Number] 58 | G --> H[Use as Next
Milestone Number] 59 | B --> I{No Matching
Directories?} 60 | I -->|Yes| J[Start with 1] 61 | J --> H 62 | ``` 63 | 64 | #### Implementation Steps 65 | 66 | 1. List all directories in the handoffs/ directory 67 | 2. Filter to only include directories matching the pattern `[0-9]+-*` 68 | 3. Extract the numeric prefix from each directory name 69 | 4. Sort numerically by prefix 70 | 5. Select the highest number and increment 71 | 6. If no existing milestone directories, start with 1 72 | 73 | #### Examples 74 | 75 | | Existing Directories | Next Number | 76 | |----------------------|-------------| 77 | | 1-feature/, 2-refactor/ | 3 | 78 | | None | 1 | 79 | | 1-feature/, 3-database/ | 4 | 80 | | 5-refactor/ | 6 | 81 | 82 | > **Critical Warning:** Always verify that you're examining the correct directory level when determining numbering. Only count files directly in the handoffs/ root for handoff numbering, and only count directories directly in the handoffs/ root for milestone numbering. -------------------------------------------------------------------------------- /handoff-system/1-handoff-custom-mode/components/8-session-restoration.md: -------------------------------------------------------------------------------- 1 | 2 | ==== 3 | 4 | # Session Restoration 5 | 6 | ## Restoration Process 7 | 8 | When restoring a session from existing handoffs and milestones: 9 | 10 | ### Document Reading Order 11 | 12 | Follow this specific order to efficiently restore context: 13 | 14 | 1. First read milestone summaries in numerical order (e.g., 1-feature/, 2-refactor/) 15 | - Focus ONLY on 0-prefixed documents within milestone directories 16 | - Start with older milestones and move to newer ones 17 | 18 | 2. Then read any handoff documents in the root directory in numerical order 19 | - Pay special attention to the most recent handoff for current state 20 | - These represent the most recent work not yet consolidated into milestones 21 | 22 | ### Information Prioritization 23 | 24 | When analyzing the documents, prioritize information in this order: 25 | 26 | | Priority | Information Type | Reason | 27 | |----------|------------------|--------| 28 | | Highest | Priority Development Requirements (PDR) | Indicates what needs immediate attention | 29 | | High | Unresolved problems and partial solutions | Ongoing issues that need resolution | 30 | | High | Work in progress and completion percentage | Continuing tasks that need further work | 31 | | Medium | Deviations from original plans | Important context for current approach | 32 | | Medium | Recent decisions and their rationale | Understanding of current direction | 33 | | Lower | Completed features | Background context | 34 | 35 | ### Verification Steps 36 | 37 | Before proceeding with project work: 38 | 1. List all milestone directories in numerical order 39 | 2. List all handoff documents you've read 40 | 3. Summarize the current project state and next steps 41 | 42 | ## Context Loading Optimization 43 | 44 | To maximize context efficiency during restoration: 45 | 46 | ``` 47 | ┌─────────────────────────────────────────┐ 48 | │ Context Loading Strategy │ 49 | ├─────────────────────┬───────────────────┤ 50 | │ Older Milestones │ Summary Only │ 51 | │ Recent Milestones │ Full Details │ 52 | │ Handoffs in Root │ All Details │ 53 | │ Latest Handoff │ Maximum Attention │ 54 | └─────────────────────┴───────────────────┘ 55 | ``` 56 | 57 | - Load only summary documents when reviewing older milestones 58 | - Focus on the most recent 2-3 handoffs for detailed context 59 | - Use milestone summaries for high-level project understanding 60 | - Reference specific documents for detailed information when needed 61 | 62 | > **Insight:** The most valuable context is often found in the most recent handoff document, which represents the current state of the project. -------------------------------------------------------------------------------- /handoff-system/1-handoff-custom-mode/components/9-conversation-extraction.md: -------------------------------------------------------------------------------- 1 | 2 | ==== 3 | 4 | # Conversation Extraction 5 | 6 | ## Overview 7 | 8 | The conversation extraction feature enhances handoff documents by analyzing cleaned conversation exports. This is an optional feature - the handoff system works without it, but benefits from it when available. 9 | 10 | ```mermaid 11 | graph TD 12 | A[User saves conversation
to chat-history] -->|Step 1| B[Check using shell commands] 13 | B -->|Step 2| C[Run extraction script] 14 | C -->|Step 3| D[Clean file saved with
proper numbering] 15 | C -->|Step 4| E[Original file deleted] 16 | D --> F[Analyze for handoff] 17 | ``` 18 | 19 | ## ⚠️ IMPORTANT: Safety Rules for Large Files 20 | 21 | To prevent context overflow and performance issues: 22 | 23 | 1. **Never directly read files** from the `chat-history` directory 24 | 2. **Always use extraction scripts** to process raw conversation exports 25 | 3. **Work only with the extracted files** in the main handoffs directory 26 | 27 | ## Chat History Detection Protocol 28 | 29 | 1. **ALWAYS check for files in chat-history using SHELL COMMANDS ONLY**: 30 | ```bash 31 | # On Unix/Linux/macOS: 32 | ls -la handoffs/0-system/chat-history 33 | # On Windows: 34 | dir handoffs\0-system\chat-history 35 | ``` 36 | 37 | 2. **If files exist**, run the extraction script: 38 | ```bash 39 | # Run the script from the project root: 40 | python handoffs/0-system/scripts/1-extract_conversation.py 41 | ``` 42 | 43 | If Python fails: 44 | ```bash 45 | node handoffs/0-system/scripts/1-extract-conversation.js 46 | ``` 47 | 48 | 3. **Wait for extraction to complete** before proceeding with any handoff operations 49 | 50 | ## Directory Structure 51 | 52 | ``` 53 | handoffs/ 54 | ├── 0-system/ 55 | │ ├── chat-history/ # RESTRICTED - Place raw exports here 56 | │ │ └── conversation.md # Potentially large files - never read directly 57 | │ └── scripts/ # Extraction and processing scripts 58 | ├── 1-chat_transcript.md # Processed file from extraction script 59 | └── 2-feature-handoff.md # Regular handoff document 60 | ``` 61 | 62 | ## Using Extraction Scripts 63 | 64 | The system includes scripts for cleaning conversation exports. 65 | 66 | When running scripts: 67 | - Scripts automatically find files in the chat-history directory 68 | - Processed files are saved with sequential numbering (e.g., 1-chat_transcript.md) 69 | - Original files are deleted after successful extraction 70 | 71 | > **Critical Warning:** Never attempt to read potentially large files from the chat-history directory directly. Always use the extraction scripts to create a cleaned version first. -------------------------------------------------------------------------------- /handoff-system/1-handoff-custom-mode/components/4-restoration-flowchart.md: -------------------------------------------------------------------------------- 1 | 2 | ==== 3 | 4 | # Session Restoration Workflow 5 | 6 | Follow this detailed workflow diagram when restoring a session from handoffs or milestones: 7 | 8 | ```mermaid 9 | graph TD 10 | Start[Begin Session Restoration] --> ScanDir[Scan Project Directory] 11 | ScanDir --> FindHandoffs{Handoff Directory
Found?} 12 | 13 | FindHandoffs -->|Yes| CheckHandoffs{Handoffs in
Root Directory?} 14 | FindHandoffs -->|No| SuggestCreate[Suggest Creating
Handoff Structure] 15 | SuggestCreate --> End 16 | 17 | CheckHandoffs -->|Yes| ReadMilestones[Read All Milestone
Summary Documents
in Sequential Order] 18 | CheckHandoffs -->|No| MilestonesOnly[Read Only Milestone
Summaries] 19 | 20 | ReadMilestones --> ReadHandoffs[Read All Handoff
Documents in
Sequential Order] 21 | ReadHandoffs --> CheckExtract{Conversation
Extract Available?} 22 | 23 | MilestonesOnly --> CheckExtract 24 | 25 | CheckExtract -->|Yes| ProcessExtract[Process Conversation
Extract for Context] 26 | CheckExtract -->|No| SkipExtract[Continue Without
Conversation Extract] 27 | 28 | ProcessExtract --> SummarizeState[Summarize Current
Project State] 29 | SkipExtract --> SummarizeState 30 | 31 | SummarizeState --> VerifyUnderstanding[Verify Understanding
with User] 32 | VerifyUnderstanding --> ReadProjectFiles[Read Key Project Files
Mentioned in Handoffs] 33 | ReadProjectFiles --> ReportReady[Report Context
Restoration Complete] 34 | ReportReady --> End[Begin Project Work] 35 | ``` 36 | 37 | ## Restoration Decision Points 38 | 39 | At each decision point in the workflow: 40 | 41 | ### 1. Finding Handoff Directory 42 | - Search for the handoffs directory in the project 43 | - If not found, suggest creating the structure and explain the benefits 44 | 45 | ### 2. Checking for Handoffs 46 | - Determine if there are handoff files in the root handoffs directory 47 | - If yes, they represent the most recent work and should be read last 48 | - If no, only milestone summaries need to be read 49 | 50 | ### 3. Processing Conversation Extract 51 | - If a conversation extract is available, analyze it for additional context 52 | - This is optional - the system works fine without it 53 | 54 | ### 4. Verification 55 | - Before proceeding, verify your understanding of the project state 56 | - List all milestone directories and handoff documents you've read 57 | - Summarize the key aspects of the current project state 58 | 59 | > **Best Practice:** When restoring context, focus on the most recent documents first, as they contain the most relevant information about the current project state. -------------------------------------------------------------------------------- /personal_roo_docs/normal/README.md: -------------------------------------------------------------------------------- 1 | # Roo Code: User-Friendly Documentation 2 | 3 | This directory contains practical guides for everyday Roo Code users. These documents focus on how to use Roo's features without diving into technical implementation details. 4 | 5 | ## Available Guides 6 | 7 | ### Core Features 8 | 9 | | Document | Description | Purpose | 10 | |----------|-------------|---------| 11 | | [Browser Automation](browser-automation.md) | Guide to Roo's browser control capabilities | Learn how to make Roo interact with websites, fill forms, and capture screenshots | 12 | | [Checkpoint System](checkpoint-system.md) | Using Roo's workspace state tracking | Discover how to use checkpoints to track changes and restore previous workspace states | 13 | | [Context Mentions](context-mentions.md) | How Roo references specific content | Understand how Roo can reference specific parts of code or text in conversations | 14 | | [Conversation Extraction](conversation-extraction.md) | Exporting your chat history | Learn how to save, share, and reuse your conversations with Roo | 15 | | [Custom Modes](custom-modes.md) | Creating specialized AI behaviors | Guide to creating custom modes for different roles and tasks | 16 | | [Custom Rules](custom-rules.md) | Setting rules for Roo's behavior | Learn how to guide Roo's actions with project-specific rules | 17 | | [Custom System Prompts](custom-system-prompts.md) | Customizing Roo's core behavior | Understand how to modify Roo's fundamental behavior with system prompts | 18 | | [Experimental Features](experimental-features.md) | New features in development | Explore cutting-edge features being developed for Roo | 19 | 20 | ### Advanced Features 21 | 22 | | Document | Description | Purpose | 23 | |----------|-------------|---------| 24 | | [File Filtering](file-filtering.md) | Controlling which files Roo can see | Learn how to selectively include or exclude files from Roo's visibility | 25 | | [Managing Context Window](managing-context-window.md) | Optimizing Roo's memory | Practical tips for managing what Roo remembers during conversations | 26 | | [Managing Preferences](managing-preferences.md) | Configuring Roo's behavior | Guide to adjusting settings to customize how Roo operates | 27 | | [MCP Server Integration](mcp-server-integration.md) | Connecting Roo to external tools | Learn how to extend Roo's capabilities with Model Context Protocol servers | 28 | | [Optimizing Context Usage](optimizing-context-usage.md) | Getting the most from Roo's memory | Advanced techniques for maximizing the efficiency of Roo's context window | 29 | | [Rooignore Configuration](rooignore-configuration.md) | Excluding files from Roo | How to use .rooignore files to control what files Roo can access | 30 | | [Task Management](task-management.md) | Organizing your conversations | Guide to managing multiple conversations and tasks with Roo | -------------------------------------------------------------------------------- /handoffs/0-instructions/0-intro.md: -------------------------------------------------------------------------------- 1 | # Handoff and Milestone System 2 | 3 | ## Core Concept 4 | 5 | This system enables efficient knowledge transfer between LLM sessions through: 6 | 1. Handoffs: Sequential session reports capturing completed work 7 | 2. Milestones: Consolidated knowledge from multiple handoffs 8 | 9 | ## Documents Structure 10 | 11 | **Handoffs**: 12 | - Numbered sequentially (1-setup.md, 2-implementation.md) 13 | - Located in handoffs/ root directory 14 | - Contain specific completed work details 15 | 16 | **Milestones**: 17 | - Stored in numbered folders (1-feature-complete/) 18 | - Consolidate multiple handoff documents 19 | - Summarize achievements and lessons learned 20 | 21 | ## Creation Triggers 22 | 23 | **Create handoff documents when**: 24 | - Completing a significant project segment 25 | - Context becomes ~30% irrelevant to current task 26 | - After 10+ conversation exchanges 27 | - During debugging sessions exceeding 5 exchanges without resolution 28 | 29 | **Create milestone documents when**: 30 | - Major feature/component implementation complete 31 | - Project phase completed 32 | - 3-5 handoffs accumulated since last milestone 33 | - Critical problem solved with valuable lessons 34 | - Project reaches stable/deployable state 35 | 36 | ## Context Assessment Process 37 | 38 | Before each major response: 39 | 1. Review context window contents: 40 | - Most relevant: current task, recent files, active discussions 41 | - Moderately relevant: background information, earlier work 42 | - Low relevance: initial setup, tangential discussions 43 | 2. Determine if handoff needed based on assessment 44 | 45 | ## Implementation 46 | 47 | Add to project's `.clinerules` file: 48 | 49 | ``` 50 | Assess context relevance after each substantive exchange. Create handoff documents in the handoffs/ directory when context becomes diluted with irrelevant information, after completing discrete project segments, or during prolonged debugging sessions. Create milestone documents in handoffs/ subdirectories when completing major features or after 3-5 related handoffs accumulate. A fresh LLM session with focused context often solves problems that an overloaded session cannot. 51 | ``` 52 | 53 | ## Compatibility 54 | 55 | Optimized for Claude 3.7 Sonnet with thinking enabled (2k-8k reasoning capacity). 56 | 57 | ## Process Flow 58 | 59 | 1. Create sequential handoff documents during development 60 | 2. Generate milestone when threshold conditions met 61 | 3. Create milestone folder and move relevant handoff files 62 | 4. Create summary documentation in milestone folder 63 | 64 | ## Reference Documentation 65 | 66 | - [1-handoff-instructions.md](./1-handoff-instructions.md): Handoff document format 67 | - [2-milestone-instructions.md](./2-milestone-instructions.md): Milestone process 68 | - [3-milestone-scripts.md](./3-milestone-scripts.md): Automation scripts -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/lib/src/2-backup.js: -------------------------------------------------------------------------------- 1 | /** 2 | * Backup functions for the installer 3 | */ 4 | 5 | const fs = require('fs'); 6 | const path = require('path'); 7 | 8 | /** 9 | * Handle files and directories that need to be backed up 10 | * @param {string} targetDir - Target installation directory 11 | * @returns {Object} - Map of paths to their backup locations 12 | */ 13 | function backupExistingInstallation(targetDir) { 14 | console.log('\nChecking for existing handoff system installation...'); 15 | const backupPaths = {}; 16 | 17 | // Check if handoffs directory exists - this is the main indicator of an existing installation 18 | const handoffsDir = path.join(targetDir, 'handoffs'); 19 | if (fs.existsSync(handoffsDir)) { 20 | console.log('- Existing handoff system detected'); 21 | 22 | // Backup the entire handoffs directory 23 | const handoffsBackupDir = `${handoffsDir}-backup`; 24 | let backupSuffix = ''; 25 | let counter = 1; 26 | 27 | // Find available backup name 28 | while (fs.existsSync(`${handoffsBackupDir}${backupSuffix}`)) { 29 | backupSuffix = `-${counter}`; 30 | counter++; 31 | } 32 | 33 | const finalBackupPath = `${handoffsBackupDir}${backupSuffix}`; 34 | 35 | try { 36 | // Create backup directory 37 | fs.mkdirSync(finalBackupPath, { recursive: true }); 38 | console.log(`- Created backup directory: ${finalBackupPath}`); 39 | 40 | // Copy all existing files to backup instead of renaming 41 | // This preserves the original in case of installation failure 42 | const copyDirRecursive = (src, dest) => { 43 | // Create destination directory 44 | fs.mkdirSync(dest, { recursive: true }); 45 | 46 | // Read directory contents 47 | const entries = fs.readdirSync(src, { withFileTypes: true }); 48 | 49 | for (const entry of entries) { 50 | const srcPath = path.join(src, entry.name); 51 | const destPath = path.join(dest, entry.name); 52 | 53 | if (entry.isDirectory()) { 54 | // Recursive call for directories 55 | copyDirRecursive(srcPath, destPath); 56 | } else { 57 | // Copy file 58 | fs.copyFileSync(srcPath, destPath); 59 | } 60 | } 61 | }; 62 | 63 | // Copy all files from handoffs to backup 64 | copyDirRecursive(handoffsDir, finalBackupPath); 65 | console.log(`- Backed up handoffs directory to ${finalBackupPath}`); 66 | backupPaths['handoffs'] = finalBackupPath; 67 | } catch (err) { 68 | console.error(`- Error backing up handoffs directory: ${err.message}`); 69 | } 70 | } else { 71 | console.log('- No existing handoff system detected'); 72 | } 73 | 74 | return backupPaths; 75 | } 76 | 77 | module.exports = { 78 | backupExistingInstallation 79 | }; -------------------------------------------------------------------------------- /handoff-system/2-scripts/README.md: -------------------------------------------------------------------------------- 1 | # Handoff System Scripts 2 | 3 | This directory contains scripts to automate common tasks in the Handoff System. 4 | 5 | ## Conversation Extraction 6 | 7 | ### 1-extract-conversation.py && 1-extract-conversation.js 8 | 9 | Processes an exported conversation file to create a clean version for handoff creation. This script combines both Python and JavaScript approaches for maximum compatibility. The python script works slightly better. 10 | 11 | ```bash 12 | node extract-conversation.js [handoffs_dir] 13 | ``` 14 | 15 | ```bash 16 | python extract-conversation.py [handoffs_dir] 17 | ``` 18 | 19 | The script: 20 | 1. Determines the next handoff number 21 | 2. Names the output file `-chat_transcript.md` (e.g., `4-chat_transcript.md`) 22 | 3. First tries the Python extraction script 23 | 4. Falls back to the JavaScript extraction script if Python fails 24 | 5. Saves the result in the handoffs directory 25 | 26 | This ensures the conversation extract is available for the handoff manager to use when creating handoff documents. 27 | 28 | ## Milestone Scripts 29 | 30 | These scripts automate the creation of milestone directories and the movement of handoff files: 31 | 32 | ### create-milestone.py (Python - Cross-platform) 33 | 34 | ```bash 35 | python create-milestone.py [milestone-name] 36 | ``` 37 | 38 | ### create-milestone.js (Node.js - Cross-platform) 39 | 40 | ```bash 41 | node create-milestone.js [milestone-name] 42 | ``` 43 | 44 | Each script performs the following steps: 45 | 46 | 1. Calculates the next sequential milestone number 47 | 2. Creates a new milestone directory with the pattern `N-milestone-name` 48 | 3. Moves all handoff documents (numbered .md files) from the handoffs root directory to the milestone directory 49 | 4. Provides a reminder to create the required summary documents 50 | 51 | ## Script Selection Guide 52 | 53 | | Environment | Preferred Script | 54 | |-------------|-----------------| 55 | | Linux/macOS | create-milestone-bash.sh | 56 | | Windows PowerShell | create-milestone-powershell.ps1 | 57 | | Python installed | create-milestone.py | 58 | | Node.js installed | create-milestone.js | 59 | 60 | For conversation extraction, the combined `extract-conversation.js` script is designed to work in all environments by trying Python first, then falling back to Node.js if needed. 61 | 62 | ## Usage within Handoff Manager 63 | 64 | The Handoff Manager can execute these scripts directly. For example: 65 | 66 | ``` 67 | I need to create a milestone for our completed feature. Please run the appropriate milestone script based on my environment. 68 | ``` 69 | 70 | ``` 71 | I need to extract the key insights from our conversation history at conversation.md. Please run the extract-conversation.js script. 72 | ``` 73 | 74 | The handoff manager will detect your environment and choose the most appropriate script to execute. -------------------------------------------------------------------------------- /handoffs/0-instructions/1-handoff-instructions.md: -------------------------------------------------------------------------------- 1 | # Shift Change: Handoff Guidelines 2 | 3 | ## Purpose 4 | Shift change report - tell next person what happened during your shift, not how to do their job. Include events and learnings not documented elsewhere. 5 | 6 | ## Information Sources 7 | 1. **Memory**: Review all previous prompts and responses 8 | 2. **Conversation**: Extract key information from entire thread 9 | 3. **Project Context**: Consider all information from the project 10 | 11 | ## Template 12 | ``` 13 | # [TOPIC] Handoff - [DATE] 14 | 15 | ## Summary 16 | [2-3 sentence overview] 17 | 18 | ## Priority Development Requirements (PDR) 19 | - **HIGH**: [Must address immediately] 20 | - **MEDIUM**: [Address soon] 21 | - **LOW**: [Be aware] 22 | 23 | ## Discoveries 24 | - [Unexpected finding 1] 25 | - [Unexpected finding 2] 26 | 27 | ## Problems & Solutions 28 | - **Problem**: [Issue description] 29 | **Solution**: [Solution applied] 30 | ```code example if needed``` 31 | 32 | ## Work in Progress 33 | - [Task 1]: [Progress %] 34 | - [Task 2]: [Progress %] 35 | 36 | ## Deviations 37 | - [Changed X to Y because Z] 38 | 39 | ## References 40 | - [doc/path1] 41 | - [doc/path2] 42 | ``` 43 | 44 | ## Include 45 | 1. **Date**: Current date at document top 46 | 2. **Summary**: Brief overview of accomplishments and status 47 | 3. **PDR**: Prioritized items needing attention (HIGH/MEDIUM/LOW) 48 | 4. **Discoveries**: Unexpected findings and insights 49 | 5. **Problems & Solutions**: Pair each problem with solution, include code when helpful 50 | 6. **Work in Progress**: Tasks still being worked on with completion estimates 51 | 7. **Deviations**: Changes from original plan/approach 52 | 8. **References**: Links to relevant docs, code, previous handoffs 53 | 54 | ## Technical Guidelines 55 | 1. **Concise Detail**: Include necessary technical details, avoid exposition 56 | 2. **Targeted Code**: Only include code snippets when they clarify a solution 57 | 3. **Actionable Info**: Focus on what next developer needs to continue 58 | 4. **Error Details**: Include exact error messages for bugs 59 | 60 | ## Exclude 61 | 1. **Documented Info**: Skip if in README, .env, docs 62 | 2. **How-to Info**: Don't explain standard procedures 63 | 3. **General Context**: Don't explain basics if documented elsewhere 64 | 65 | ## Structure 66 | 1. **Numbering**: Use sequential numbers per directory (1-setup.md) 67 | 2. **Brevity**: Be concise but thorough 68 | 3. **Organization**: Use chronological or priority structure 69 | 4. **Visuals**: Use mermaid charts for complex workflows 70 | ```mermaid 71 | graph TD 72 | A[Problem] --> B[Solution 1] 73 | A --> C[Solution 2] 74 | ``` 75 | 76 | ## Example 77 | ❌ `The auth system uses JWT tokens with 24h expiry.` 78 | 79 | ✅ `[2025-02-25] Login failures caused by timezone in token validation. Fixed with UTC standardization.` 80 | 81 | Remember: Pass the baton - share only what isn't obvious from existing documentation. -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/esm.mjs: -------------------------------------------------------------------------------- 1 | import _copy from './copy/index.js' 2 | import _empty from './empty/index.js' 3 | import _ensure from './ensure/index.js' 4 | import _json from './json/index.js' 5 | import _mkdirs from './mkdirs/index.js' 6 | import _move from './move/index.js' 7 | import _outputFile from './output-file/index.js' 8 | import _pathExists from './path-exists/index.js' 9 | import _remove from './remove/index.js' 10 | 11 | // NOTE: Only exports fs-extra's functions; fs functions must be imported from "node:fs" or "node:fs/promises" 12 | 13 | export const copy = _copy.copy 14 | export const copySync = _copy.copySync 15 | export const emptyDirSync = _empty.emptyDirSync 16 | export const emptydirSync = _empty.emptydirSync 17 | export const emptyDir = _empty.emptyDir 18 | export const emptydir = _empty.emptydir 19 | export const createFile = _ensure.createFile 20 | export const createFileSync = _ensure.createFileSync 21 | export const ensureFile = _ensure.ensureFile 22 | export const ensureFileSync = _ensure.ensureFileSync 23 | export const createLink = _ensure.createLink 24 | export const createLinkSync = _ensure.createLinkSync 25 | export const ensureLink = _ensure.ensureLink 26 | export const ensureLinkSync = _ensure.ensureLinkSync 27 | export const createSymlink = _ensure.createSymlink 28 | export const createSymlinkSync = _ensure.createSymlinkSync 29 | export const ensureSymlink = _ensure.ensureSymlink 30 | export const ensureSymlinkSync = _ensure.ensureSymlinkSync 31 | export const readJson = _json.readJson 32 | export const readJSON = _json.readJSON 33 | export const readJsonSync = _json.readJsonSync 34 | export const readJSONSync = _json.readJSONSync 35 | export const writeJson = _json.writeJson 36 | export const writeJSON = _json.writeJSON 37 | export const writeJsonSync = _json.writeJsonSync 38 | export const writeJSONSync = _json.writeJSONSync 39 | export const outputJson = _json.outputJson 40 | export const outputJSON = _json.outputJSON 41 | export const outputJsonSync = _json.outputJsonSync 42 | export const outputJSONSync = _json.outputJSONSync 43 | export const mkdirs = _mkdirs.mkdirs 44 | export const mkdirsSync = _mkdirs.mkdirsSync 45 | export const mkdirp = _mkdirs.mkdirp 46 | export const mkdirpSync = _mkdirs.mkdirpSync 47 | export const ensureDir = _mkdirs.ensureDir 48 | export const ensureDirSync = _mkdirs.ensureDirSync 49 | export const move = _move.move 50 | export const moveSync = _move.moveSync 51 | export const outputFile = _outputFile.outputFile 52 | export const outputFileSync = _outputFile.outputFileSync 53 | export const pathExists = _pathExists.pathExists 54 | export const pathExistsSync = _pathExists.pathExistsSync 55 | export const remove = _remove.remove 56 | export const removeSync = _remove.removeSync 57 | 58 | export default { 59 | ..._copy, 60 | ..._empty, 61 | ..._ensure, 62 | ..._json, 63 | ..._mkdirs, 64 | ..._move, 65 | ..._outputFile, 66 | ..._pathExists, 67 | ..._remove 68 | } 69 | -------------------------------------------------------------------------------- /handoff-system/1-handoff-custom-mode/components/7-milestone-creation.md: -------------------------------------------------------------------------------- 1 | 2 | ==== 3 | 4 | # Milestone Document Creation 5 | 6 | ## Milestone Directory Structure 7 | 8 | Each milestone directory contains these files: 9 | 10 | ### 1. 0-milestone-summary.md 11 | 12 | ```markdown 13 | # [Project/Feature] Milestone Summary - [DATE] 14 | 15 | ## Changes Implemented 16 | - [Major change 1] 17 | - [Major change 2] 18 | 19 | ## Key Decisions 20 | - [Decision 1]: [Rationale] 21 | - [Decision 2]: [Rationale] 22 | 23 | ## Discoveries 24 | - [Important finding 1] 25 | - [Important finding 2] 26 | 27 | ## Current System State 28 | - [Component 1]: [Status] 29 | - [Component 2]: [Status] 30 | ``` 31 | 32 | ### 2. 0-lessons-learned.md 33 | 34 | ```markdown 35 | # Lessons Learned - [Feature/Component] 36 | 37 | ## [Problem Category 1] 38 | 39 | **Problem:** [Issue description] 40 | 41 | **Solution:** 42 | - [Step 1] 43 | - [Step 2] 44 | - [Step 3] 45 | 46 | ## [Problem Category 2] 47 | 48 | **Problem:** [Issue description] 49 | 50 | **Solution:** 51 | - [Implementation details] 52 | - [Code patterns to use] 53 | ``` 54 | 55 | ## Creation Process 56 | 57 | The milestone creation process requires: 58 | 59 | ### 1. Directory Creation 60 | 61 | Create milestone directory with format: `N-milestone-name` 62 | - Use sequential numbering based on existing milestone directories 63 | - Use descriptive name reflecting the milestone's focus 64 | 65 | ### 2. Handoff Organization 66 | 67 | Move all numbered handoff documents from the handoffs/ root into the milestone directory 68 | - Use appropriate file system scripts (see 0-system/instructions/3-milestone-scripts.md) 69 | - Verify successful file movement 70 | - Do NOT move any files from the 0-system directory 71 | 72 | | Language | Script Example | 73 | |----------|---------------| 74 | | Bash | `find handoffs/ -maxdepth 1 -type d -name "[0-9]*-*" | sort -V | tail -n1 | sed -E 's/.*\/([0-9]+).*/\1/' | awk '{print $1+1}' | xargs -I {} mkdir -p "handoffs/{}-milestone-name"; find handoffs/ -maxdepth 1 -type f -name "[1-9]*.md" -exec mv {} "handoffs/$milestone-name/" \;` | 75 | | PowerShell | `$milestone = (Get-ChildItem "handoffs" -Directory | Where {$_.Name -match "^\d+-"} | ForEach {[int]($_.Name -split "-")[0]} | Measure -Max).Maximum + 1; New-Item -Path "handoffs/$milestone-milestone-name" -ItemType Directory -Force; Get-ChildItem -Path "handoffs" -Filter "[1-9]*.md" | Move-Item -Destination "handoffs/$milestone-milestone-name/"` | 76 | 77 | ### 3. Summary Generation 78 | 79 | - Distill essential information from all related handoffs 80 | - Focus on patterns across multiple handoffs 81 | - Prioritize technical insights and reusable knowledge 82 | - Structure information for easy reference 83 | 84 | ## Recommended Milestone Timing 85 | 86 | Create milestones when: 87 | - 3-5 handoffs have accumulated 88 | - A major feature or component is completed 89 | - A significant project phase has concluded 90 | - Critical problems have been solved with valuable lessons 91 | 92 | > **Critical Step:** Always create a final handoff documenting the most recent work before creating a milestone. This ensures the milestone captures the complete picture. -------------------------------------------------------------------------------- /handoff-manager/handoffs/0-system/instructions/prompts/CH-create-handoff-with-extraction.md: -------------------------------------------------------------------------------- 1 | # Creating a Handoff with Conversation Extraction 2 | 3 | Use this prompt when you need to create a handoff document that incorporates insights from an exported conversation. 4 | 5 | ## Complete Workflow Prompt 6 | 7 | ``` 8 | I need to create a handoff document with conversation extraction. I've exported the conversation as conversation.md. 9 | 10 | Please: 11 | 1. Determine the next sequential handoff number 12 | 2. Process the conversation export using the extraction scripts: 13 | - First try: python handoffs/chat_history/extract_conversation.py conversation.md handoffs/-chat_transcript.md 14 | - If that fails, try: node handoffs/chat_history/extract_conversation.js conversation.md handoffs/-chat_transcript.md 15 | 3. Read and analyze the extracted content 16 | 4. Compare the extraction insights with your own conversation introspection 17 | 5. Create a comprehensive handoff document that incorporates both perspectives 18 | ``` 19 | 20 | ## With Topic Focus 21 | 22 | ``` 23 | I need to create a handoff document focused on [TOPIC] with conversation extraction. I've exported the conversation as conversation.md. 24 | 25 | Please follow the conversation extraction workflow and emphasize: 26 | - [KEY ASPECT 1] 27 | - [KEY ASPECT 2] 28 | - [KEY ASPECT 3] 29 | ``` 30 | 31 | ## Custom Export Location 32 | 33 | ``` 34 | I need to create a handoff document with conversation extraction. I've exported the conversation to [CUSTOM_PATH]. 35 | 36 | Please process this export and follow the handoff creation workflow. 37 | ``` 38 | 39 | ## For Larger Conversations 40 | 41 | For particularly large conversation exports: 42 | 43 | ``` 44 | I need to create a handoff document based on a large conversation export at conversation.md. Please: 45 | 46 | 1. Process the export with the extraction script 47 | 2. Focus on identifying the most important: 48 | - Technical decisions and their rationale 49 | - Problems encountered and solutions implemented 50 | - Discoveries and unexpected findings 51 | - Current work progress percentage estimates 52 | ``` 53 | 54 | ## Best Practices 55 | 56 | When creating handoffs with conversation extraction: 57 | 58 | 1. **Focus on Unique Insights**: Prioritize information that wouldn't be obvious from code or documentation alone 59 | 2. **Cross-Reference**: Combine insights from both extraction and introspection 60 | 3. **Pattern Recognition**: Identify recurring themes or issues across the conversation 61 | 4. **Quote Selectively**: Use direct quotes from the conversation only when particularly insightful 62 | 5. **Maintain Structure**: Ensure all standard handoff sections are properly completed 63 | 64 | ## Extraction Error Handling 65 | 66 | If both extraction scripts fail: 67 | 68 | ``` 69 | I need to create a handoff document. I tried to export our conversation but the extraction failed. 70 | 71 | Please: 72 | 1. Create a handoff based on your introspection of our conversation 73 | 2. Note in the handoff that conversation extraction was attempted but failed 74 | 3. Focus particularly on capturing the key technical decisions and progress -------------------------------------------------------------------------------- /handoff-system/2-scripts/2-create-milestone.js: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env node 2 | /** 3 | * Milestone Creation Script (Node.js) 4 | * Creates a new milestone directory and moves handoff files 5 | * 6 | * Usage: 7 | * node create-milestone.js [milestone-name] 8 | */ 9 | 10 | const fs = require('fs'); 11 | const path = require('path'); 12 | const readline = require('readline'); 13 | 14 | // Create readline interface for user input 15 | const rl = readline.createInterface({ 16 | input: process.stdin, 17 | output: process.stdout 18 | }); 19 | 20 | /** 21 | * Creates a milestone directory and moves handoff files 22 | * @param {string} milestoneName - Name for the milestone 23 | */ 24 | async function createMilestone(milestoneName) { 25 | try { 26 | // Get the next milestone number 27 | const handoffsDir = 'handoffs'; 28 | 29 | // Check if handoffs directory exists 30 | if (!fs.existsSync(handoffsDir)) { 31 | console.error(`Error: Directory '${handoffsDir}' not found`); 32 | process.exit(1); 33 | } 34 | 35 | // Find milestone directories 36 | const dirs = fs.readdirSync(handoffsDir) 37 | .filter(d => fs.statSync(path.join(handoffsDir, d)).isDirectory() && /^\d+-/.test(d)); 38 | 39 | // Determine next milestone number 40 | let nextNum = 1; 41 | if (dirs.length > 0) { 42 | // Extract numbers from directory names and find the highest 43 | const maxNum = Math.max(...dirs.map(d => parseInt(d.match(/^(\d+)-/)[1]) || 0)); 44 | nextNum = maxNum + 1; 45 | } 46 | 47 | // If milestone name wasn't provided, prompt for it 48 | if (!milestoneName) { 49 | milestoneName = await new Promise(resolve => { 50 | rl.question('Enter milestone name: ', answer => resolve(answer)); 51 | }); 52 | } 53 | 54 | // Create milestone directory 55 | const milestoneDir = path.join(handoffsDir, `${nextNum}-${milestoneName}`); 56 | fs.mkdirSync(milestoneDir, { recursive: true }); 57 | console.log(`Created milestone directory: ${milestoneDir}`); 58 | 59 | // Find handoff files 60 | const handoffFiles = fs.readdirSync(handoffsDir) 61 | .filter(f => /^[1-9].*\.md$/.test(f) && fs.statSync(path.join(handoffsDir, f)).isFile()); 62 | 63 | // Move handoff files 64 | let movedCount = 0; 65 | for (const file of handoffFiles) { 66 | const srcPath = path.join(handoffsDir, file); 67 | const destPath = path.join(milestoneDir, file); 68 | fs.renameSync(srcPath, destPath); 69 | movedCount++; 70 | } 71 | 72 | console.log(`Moved ${movedCount} handoff files to milestone directory`); 73 | console.log(`Milestone ${nextNum}-${milestoneName} created successfully.`); 74 | console.log(`Don't forget to create 0-milestone-summary.md and 0-lessons-learned.md files in the milestone directory.`); 75 | 76 | rl.close(); 77 | } catch (error) { 78 | console.error(`Error creating milestone: ${error.message}`); 79 | rl.close(); 80 | process.exit(1); 81 | } 82 | } 83 | 84 | // Get milestone name from command line arguments 85 | const milestoneName = process.argv[2]; 86 | 87 | // Call the function 88 | createMilestone(milestoneName); -------------------------------------------------------------------------------- /handoff-manager/handoffs/0-system/scripts/2-create-milestone.js: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env node 2 | /** 3 | * Milestone Creation Script (Node.js) 4 | * Creates a new milestone directory and moves handoff files 5 | * 6 | * Usage: 7 | * node create-milestone.js [milestone-name] 8 | */ 9 | 10 | const fs = require('fs'); 11 | const path = require('path'); 12 | const readline = require('readline'); 13 | 14 | // Create readline interface for user input 15 | const rl = readline.createInterface({ 16 | input: process.stdin, 17 | output: process.stdout 18 | }); 19 | 20 | /** 21 | * Creates a milestone directory and moves handoff files 22 | * @param {string} milestoneName - Name for the milestone 23 | */ 24 | async function createMilestone(milestoneName) { 25 | try { 26 | // Get the next milestone number 27 | const handoffsDir = 'handoffs'; 28 | 29 | // Check if handoffs directory exists 30 | if (!fs.existsSync(handoffsDir)) { 31 | console.error(`Error: Directory '${handoffsDir}' not found`); 32 | process.exit(1); 33 | } 34 | 35 | // Find milestone directories 36 | const dirs = fs.readdirSync(handoffsDir) 37 | .filter(d => fs.statSync(path.join(handoffsDir, d)).isDirectory() && /^\d+-/.test(d)); 38 | 39 | // Determine next milestone number 40 | let nextNum = 1; 41 | if (dirs.length > 0) { 42 | // Extract numbers from directory names and find the highest 43 | const maxNum = Math.max(...dirs.map(d => parseInt(d.match(/^(\d+)-/)[1]) || 0)); 44 | nextNum = maxNum + 1; 45 | } 46 | 47 | // If milestone name wasn't provided, prompt for it 48 | if (!milestoneName) { 49 | milestoneName = await new Promise(resolve => { 50 | rl.question('Enter milestone name: ', answer => resolve(answer)); 51 | }); 52 | } 53 | 54 | // Create milestone directory 55 | const milestoneDir = path.join(handoffsDir, `${nextNum}-${milestoneName}`); 56 | fs.mkdirSync(milestoneDir, { recursive: true }); 57 | console.log(`Created milestone directory: ${milestoneDir}`); 58 | 59 | // Find handoff files 60 | const handoffFiles = fs.readdirSync(handoffsDir) 61 | .filter(f => /^[1-9].*\.md$/.test(f) && fs.statSync(path.join(handoffsDir, f)).isFile()); 62 | 63 | // Move handoff files 64 | let movedCount = 0; 65 | for (const file of handoffFiles) { 66 | const srcPath = path.join(handoffsDir, file); 67 | const destPath = path.join(milestoneDir, file); 68 | fs.renameSync(srcPath, destPath); 69 | movedCount++; 70 | } 71 | 72 | console.log(`Moved ${movedCount} handoff files to milestone directory`); 73 | console.log(`Milestone ${nextNum}-${milestoneName} created successfully.`); 74 | console.log(`Don't forget to create 0-milestone-summary.md and 0-lessons-learned.md files in the milestone directory.`); 75 | 76 | rl.close(); 77 | } catch (error) { 78 | console.error(`Error creating milestone: ${error.message}`); 79 | rl.close(); 80 | process.exit(1); 81 | } 82 | } 83 | 84 | // Get milestone name from command line arguments 85 | const milestoneName = process.argv[2]; 86 | 87 | // Call the function 88 | createMilestone(milestoneName); -------------------------------------------------------------------------------- /handoff-system/0-instructions/prompts/CM-create-milestone.md: -------------------------------------------------------------------------------- 1 | # Creating a Milestone 2 | 3 | Use this prompt when you need to create a new milestone to consolidate accumulated handoffs. 4 | 5 | ## Workflow-Guided Prompt 6 | 7 | ``` 8 | I need to create a milestone for our completed [FEATURE/COMPONENT]. Please follow the milestone creation workflow. 9 | ``` 10 | 11 | ## Standard Prompt Template 12 | 13 | ``` 14 | I need to create a milestone for our completed [FEATURE/COMPONENT]. Please: 15 | 16 | 1. Follow the milestone creation workflow to: 17 | - Check if handoffs exist in the root directory 18 | - Verify enough handoffs have accumulated (3-5) 19 | - Ensure a recent final handoff exists 20 | - Calculate the next milestone number 21 | - Create the milestone directory structure 22 | - Move handoff files to the milestone directory 23 | - Generate summary documents 24 | ``` 25 | 26 | ## Enhanced Context 27 | 28 | For more targeted milestone creation: 29 | 30 | ``` 31 | I need to create a milestone for our completed [FEATURE/COMPONENT]. Please: 32 | 33 | 1. Follow the milestone creation workflow 34 | 2. Focus these aspects in the milestone summary: 35 | - [KEY ACHIEVEMENT 1] 36 | - [KEY ACHIEVEMENT 2] 37 | - [KEY DECISION POINT 1] 38 | 3. Organize the handoffs with particular attention to: 39 | - [SPECIFIC PATTERN OR THEME] 40 | ``` 41 | 42 | ## Script Assistance 43 | 44 | For help with file organization: 45 | 46 | ``` 47 | I need to create a milestone and move files. Please: 48 | 49 | 1. Follow the milestone creation workflow 50 | 2. Suggest the appropriate script from 3-milestone-scripts.md 51 | 3. Adapt the script for our [BASH/POWERSHELL/PYTHON/NODE] environment 52 | ``` 53 | 54 | ## Milestone Numbering Logic 55 | 56 | The handoff-manager uses a reliable numbering algorithm: 57 | 58 | 1. List all directories in the handoffs/ directory 59 | 2. Filter to include only directories matching `[0-9]+-*` 60 | 3. Extract the numeric prefix from each directory name 61 | 4. Sort numerically by prefix 62 | 5. Select the highest number and increment 63 | 6. If no existing milestone directories, start with 1 64 | 65 | ## Critical Process Steps 66 | 67 | 1. **Pre-milestone Check**: 68 | - Verify handoffs exist in root directory 69 | - Check if 3-5 handoffs have accumulated 70 | - Ensure recent work is captured in final handoff 71 | 72 | 2. **Directory Creation**: 73 | - Use correct sequential number 74 | - Name directory based on milestone achievement 75 | - Format: `N-descriptive-name` (e.g., `2-user-authentication`) 76 | 77 | 3. **File Organization**: 78 | - Move all handoff files from root to milestone directory 79 | - Use scripts from 3-milestone-scripts.md 80 | - Verify successful file movement 81 | 82 | 4. **Summary Document Creation**: 83 | - Create `0-milestone-summary.md` with key accomplishments 84 | - Create `0-lessons-learned.md` with reusable patterns 85 | - Distill essential information from all handoffs 86 | 87 | The workflow ensures a logical progression: 88 | 1. Work on feature/component → Create handoffs during development 89 | 2. Complete feature/component → Create final handoff with completion status 90 | 3. Consolidate work → Create milestone that includes this final handoff 91 | -------------------------------------------------------------------------------- /handoff-manager/handoffs/0-system/instructions/prompts/CM-create-milestone.md: -------------------------------------------------------------------------------- 1 | # Creating a Milestone 2 | 3 | Use this prompt when you need to create a new milestone to consolidate accumulated handoffs. 4 | 5 | ## Workflow-Guided Prompt 6 | 7 | ``` 8 | I need to create a milestone for our completed [FEATURE/COMPONENT]. Please follow the milestone creation workflow. 9 | ``` 10 | 11 | ## Standard Prompt Template 12 | 13 | ``` 14 | I need to create a milestone for our completed [FEATURE/COMPONENT]. Please: 15 | 16 | 1. Follow the milestone creation workflow to: 17 | - Check if handoffs exist in the root directory 18 | - Verify enough handoffs have accumulated (3-5) 19 | - Ensure a recent final handoff exists 20 | - Calculate the next milestone number 21 | - Create the milestone directory structure 22 | - Move handoff files to the milestone directory 23 | - Generate summary documents 24 | ``` 25 | 26 | ## Enhanced Context 27 | 28 | For more targeted milestone creation: 29 | 30 | ``` 31 | I need to create a milestone for our completed [FEATURE/COMPONENT]. Please: 32 | 33 | 1. Follow the milestone creation workflow 34 | 2. Focus these aspects in the milestone summary: 35 | - [KEY ACHIEVEMENT 1] 36 | - [KEY ACHIEVEMENT 2] 37 | - [KEY DECISION POINT 1] 38 | 3. Organize the handoffs with particular attention to: 39 | - [SPECIFIC PATTERN OR THEME] 40 | ``` 41 | 42 | ## Script Assistance 43 | 44 | For help with file organization: 45 | 46 | ``` 47 | I need to create a milestone and move files. Please: 48 | 49 | 1. Follow the milestone creation workflow 50 | 2. Suggest the appropriate script from 3-milestone-scripts.md 51 | 3. Adapt the script for our [BASH/POWERSHELL/PYTHON/NODE] environment 52 | ``` 53 | 54 | ## Milestone Numbering Logic 55 | 56 | The handoff-manager uses a reliable numbering algorithm: 57 | 58 | 1. List all directories in the handoffs/ directory 59 | 2. Filter to include only directories matching `[0-9]+-*` 60 | 3. Extract the numeric prefix from each directory name 61 | 4. Sort numerically by prefix 62 | 5. Select the highest number and increment 63 | 6. If no existing milestone directories, start with 1 64 | 65 | ## Critical Process Steps 66 | 67 | 1. **Pre-milestone Check**: 68 | - Verify handoffs exist in root directory 69 | - Check if 3-5 handoffs have accumulated 70 | - Ensure recent work is captured in final handoff 71 | 72 | 2. **Directory Creation**: 73 | - Use correct sequential number 74 | - Name directory based on milestone achievement 75 | - Format: `N-descriptive-name` (e.g., `2-user-authentication`) 76 | 77 | 3. **File Organization**: 78 | - Move all handoff files from root to milestone directory 79 | - Use scripts from 3-milestone-scripts.md 80 | - Verify successful file movement 81 | 82 | 4. **Summary Document Creation**: 83 | - Create `0-milestone-summary.md` with key accomplishments 84 | - Create `0-lessons-learned.md` with reusable patterns 85 | - Distill essential information from all handoffs 86 | 87 | The workflow ensures a logical progression: 88 | 1. Work on feature/component → Create handoffs during development 89 | 2. Complete feature/component → Create final handoff with completion status 90 | 3. Consolidate work → Create milestone that includes this final handoff 91 | -------------------------------------------------------------------------------- /handoff-system/publish-handoff-manager.js: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env node 2 | /** 3 | * Handoff Publisher Runner 4 | * 5 | * This script runs the handoff-publisher package to generate the installer. 6 | * It first cleans the target handoff-manager directory to ensure a clean installation. 7 | */ 8 | 9 | const path = require('path'); 10 | const fs = require('fs'); 11 | const { spawn } = require('child_process'); 12 | 13 | // Get directory paths 14 | const publisherDir = path.join(__dirname, 'handoff-publisher'); 15 | const targetDir = path.join(__dirname, '..', 'handoff-manager', 'single-script'); 16 | 17 | /** 18 | * Recursively deletes files and subdirectories in a directory 19 | * while preserving specified directories and their contents 20 | * @param {string} dirPath - Path to the directory to clean 21 | * @param {Array} preservePaths - Paths to preserve (relative to dirPath) 22 | */ 23 | function cleanDirectory(dirPath, preservePaths = []) { 24 | if (!fs.existsSync(dirPath)) { 25 | console.log(`Creating directory: ${dirPath}`); 26 | fs.mkdirSync(dirPath, { recursive: true }); 27 | return; 28 | } 29 | 30 | // Convert preserve paths to absolute paths for easier comparison 31 | const absolutePreservePaths = preservePaths.map(p => path.join(dirPath, p)); 32 | 33 | console.log(`Cleaning directory: ${dirPath}`); 34 | const files = fs.readdirSync(dirPath); 35 | 36 | for (const file of files) { 37 | const filePath = path.join(dirPath, file); 38 | 39 | // Check if this path should be preserved 40 | const shouldPreserve = absolutePreservePaths.some(preservePath => 41 | filePath === preservePath || filePath.startsWith(preservePath + path.sep) 42 | ); 43 | 44 | if (shouldPreserve) { 45 | console.log(`Preserving: ${filePath}`); 46 | continue; 47 | } 48 | 49 | if (fs.lstatSync(filePath).isDirectory()) { 50 | // Recursively clean subdirectories then remove the directory 51 | cleanDirectory(filePath, []); // No need to pass preservePaths here as we already checked 52 | fs.rmdirSync(filePath); 53 | } else { 54 | // Remove files 55 | fs.unlinkSync(filePath); 56 | console.log(`Deleted file: ${filePath}`); 57 | } 58 | } 59 | } 60 | 61 | // Paths to preserve in the handoff-manager directory 62 | const pathsToPreserve = [ 63 | 'handoffs/0-system/chat_history', // Preserve chat history 64 | 'handoffs' // Preserve user handoffs 65 | ]; 66 | 67 | // Clean the target directory before publishing but preserve specified paths 68 | try { 69 | cleanDirectory(targetDir, pathsToPreserve); 70 | console.log(`✅ Successfully cleaned target directory while preserving specified paths`); 71 | } catch (err) { 72 | console.error(`❌ Error cleaning target directory: ${err.message}`); 73 | process.exit(1); 74 | } 75 | 76 | // Run the publisher 77 | console.log('\nRunning Handoff Publisher...'); 78 | const publisher = spawn('node', [path.join(publisherDir, 'index.js')], { 79 | stdio: 'inherit', 80 | cwd: __dirname 81 | }); 82 | 83 | publisher.on('close', (code) => { 84 | if (code === 0) { 85 | console.log('✅ Handoff Publisher completed successfully.'); 86 | } else { 87 | console.error(`❌ Handoff Publisher exited with code ${code}`); 88 | } 89 | }); -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/graceful-fs/legacy-streams.js: -------------------------------------------------------------------------------- 1 | var Stream = require('stream').Stream 2 | 3 | module.exports = legacy 4 | 5 | function legacy (fs) { 6 | return { 7 | ReadStream: ReadStream, 8 | WriteStream: WriteStream 9 | } 10 | 11 | function ReadStream (path, options) { 12 | if (!(this instanceof ReadStream)) return new ReadStream(path, options); 13 | 14 | Stream.call(this); 15 | 16 | var self = this; 17 | 18 | this.path = path; 19 | this.fd = null; 20 | this.readable = true; 21 | this.paused = false; 22 | 23 | this.flags = 'r'; 24 | this.mode = 438; /*=0666*/ 25 | this.bufferSize = 64 * 1024; 26 | 27 | options = options || {}; 28 | 29 | // Mixin options into this 30 | var keys = Object.keys(options); 31 | for (var index = 0, length = keys.length; index < length; index++) { 32 | var key = keys[index]; 33 | this[key] = options[key]; 34 | } 35 | 36 | if (this.encoding) this.setEncoding(this.encoding); 37 | 38 | if (this.start !== undefined) { 39 | if ('number' !== typeof this.start) { 40 | throw TypeError('start must be a Number'); 41 | } 42 | if (this.end === undefined) { 43 | this.end = Infinity; 44 | } else if ('number' !== typeof this.end) { 45 | throw TypeError('end must be a Number'); 46 | } 47 | 48 | if (this.start > this.end) { 49 | throw new Error('start must be <= end'); 50 | } 51 | 52 | this.pos = this.start; 53 | } 54 | 55 | if (this.fd !== null) { 56 | process.nextTick(function() { 57 | self._read(); 58 | }); 59 | return; 60 | } 61 | 62 | fs.open(this.path, this.flags, this.mode, function (err, fd) { 63 | if (err) { 64 | self.emit('error', err); 65 | self.readable = false; 66 | return; 67 | } 68 | 69 | self.fd = fd; 70 | self.emit('open', fd); 71 | self._read(); 72 | }) 73 | } 74 | 75 | function WriteStream (path, options) { 76 | if (!(this instanceof WriteStream)) return new WriteStream(path, options); 77 | 78 | Stream.call(this); 79 | 80 | this.path = path; 81 | this.fd = null; 82 | this.writable = true; 83 | 84 | this.flags = 'w'; 85 | this.encoding = 'binary'; 86 | this.mode = 438; /*=0666*/ 87 | this.bytesWritten = 0; 88 | 89 | options = options || {}; 90 | 91 | // Mixin options into this 92 | var keys = Object.keys(options); 93 | for (var index = 0, length = keys.length; index < length; index++) { 94 | var key = keys[index]; 95 | this[key] = options[key]; 96 | } 97 | 98 | if (this.start !== undefined) { 99 | if ('number' !== typeof this.start) { 100 | throw TypeError('start must be a Number'); 101 | } 102 | if (this.start < 0) { 103 | throw new Error('start must be >= zero'); 104 | } 105 | 106 | this.pos = this.start; 107 | } 108 | 109 | this.busy = false; 110 | this._queue = []; 111 | 112 | if (this.fd === null) { 113 | this._open = fs.open; 114 | this._queue.push([this._open, this.path, this.flags, this.mode, undefined]); 115 | this.flush(); 116 | } 117 | } 118 | } 119 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/lib/src-assembler.js: -------------------------------------------------------------------------------- 1 | /** 2 | * Source Code Assembler for Handoff Publisher 3 | * 4 | * This module provides functions for assembling the source code components 5 | * based on the configuration in src-config.json. 6 | */ 7 | 8 | const fs = require('fs'); 9 | const path = require('path'); 10 | 11 | // This will be set by the importer if needed 12 | let fileUtils; 13 | 14 | /** 15 | * Initialize the module with dependencies 16 | * @param {Object} dependencies - Object containing module dependencies 17 | */ 18 | function initialize(dependencies) { 19 | fileUtils = dependencies['utils']; 20 | return module.exports; 21 | } 22 | 23 | /** 24 | * Extract function implementations from source code 25 | * @param {string} source - Source code content 26 | * @returns {string} - Extracted function implementations 27 | */ 28 | function extractFunctionImplementations(source) { 29 | // Remove imports, exports, and module-specific code 30 | let code = source.replace(/const\s+\w+\s*=\s*require\(['"][^'"]+['"]\);?/g, ''); 31 | code = code.replace(/module\.exports\s*=\s*{[^}]*};?/g, ''); 32 | 33 | // Clean up the code by removing excessive blank lines 34 | code = code.replace(/\n{3,}/g, '\n\n'); 35 | 36 | return code; 37 | } 38 | 39 | /** 40 | * Assemble source code from components 41 | * @param {string} componentsPath - Path to components directory 42 | * @param {Object} srcConfig - Source configuration object 43 | * @returns {Object} The assembled source code functions by category 44 | */ 45 | function assembleSourceCode(componentsPath, srcConfig) { 46 | console.log('\nAssembling source code from components...'); 47 | console.log(`Looking for components in: ${componentsPath}`); 48 | 49 | try { 50 | let assembledComponents = {}; 51 | 52 | // Process each component in order 53 | for (const component of srcConfig.components) { 54 | if (component.file) { 55 | // This is a file component 56 | const componentPath = path.join(componentsPath, component.file); 57 | if (fs.existsSync(componentPath)) { 58 | const componentContent = fs.readFileSync(componentPath, 'utf8'); 59 | const processedContent = extractFunctionImplementations(componentContent); 60 | 61 | // Use the filename without extension as the key 62 | const componentName = component.file.replace(/\.js$/, '').replace(/^\d+-/, ''); 63 | assembledComponents[componentName] = processedContent; 64 | 65 | console.log(`- Added component: ${component.file}`); 66 | } else { 67 | const errorMsg = `Component file not found: ${component.file}`; 68 | console.error(`- ${errorMsg} (searched at ${componentPath})`); 69 | if (srcConfig.errorHandling.missingFile === "error" && 70 | !srcConfig.errorHandling.continueOnError) { 71 | throw new Error(errorMsg); 72 | } 73 | } 74 | } 75 | } 76 | 77 | console.log(`- Source code assembled from ${Object.keys(assembledComponents).length} components`); 78 | return assembledComponents; 79 | } catch (err) { 80 | console.error(`- Error assembling source code: ${err.message}`); 81 | process.exit(1); 82 | } 83 | } 84 | 85 | module.exports = { 86 | initialize, 87 | assembleSourceCode, 88 | extractFunctionImplementations 89 | }; -------------------------------------------------------------------------------- /personal_roo_docs/technical/README.md: -------------------------------------------------------------------------------- 1 | # Roo Code: Technical Documentation 2 | 3 | This directory contains in-depth technical documentation explaining how Roo Code works internally. These documents provide detailed insights into implementation details, architecture, and advanced usage patterns. 4 | 5 | ## Available Technical Documentation 6 | 7 | ### Core Implementation 8 | 9 | | Document | Description | Purpose | 10 | |----------|-------------|---------| 11 | | [Browser Automation](browser-automation.md) | Technical implementation of Puppeteer integration | Details the architecture of Roo's browser control system, including the Puppeteer bridge, screenshot processing, and event handling | 12 | | [Checkpoint System](checkpoint-system.md) | Git-based workspace state tracking | Documents the implementation of Roo's shadow repository system for tracking changes and providing restore points | 13 | | [Context Mentions](context-mentions.md) | Source reference implementation | Explains the technical mechanisms used to reference specific code sections, including the indexing and resolution algorithms | 14 | | [Conversation Extraction](conversation-extraction.md) | Task history export pipeline | Details the implementation of conversation extraction, including the parsing, filtering, and formatting mechanisms | 15 | | [Custom Modes](custom-modes.md) | Mode system architecture | Comprehensive explanation of the custom modes implementation, including validation, file restrictions, and integration points | 16 | | [Custom Rules](custom-rules.md) | Rule loading and enforcement | Technical details on how rule files are parsed, loaded, and integrated into the system prompt | 17 | | [Custom System Prompts](custom-system-prompts.md) | System prompt override mechanisms | Explains the implementation of prompt component overrides and how they interact with the core system | 18 | 19 | ### Core Systems 20 | 21 | | Document | Description | Purpose | 22 | |----------|-------------|---------| 23 | | [Experimental Features](experimental-features.md) | Feature flag implementation | Technical overview of the feature flag system used to manage experimental features | 24 | | [File Filtering](file-filtering.md) | File access control mechanisms | Documents the implementation of file filtering systems, including pattern matching and rule application | 25 | | [Managing Context Window](managing-context-window.md) | Token optimization algorithms | Technical explanation of how Roo manages and optimizes the context window to maximize token efficiency | 26 | | [Managing Preferences](managing-preferences.md) | Configuration system implementation | Details on how preferences are stored, loaded, and applied throughout the application | 27 | | [MCP Server Integration](mcp-server-integration.md) | Model Context Protocol implementation | In-depth explanation of how MCP servers are discovered, connected, and utilized | 28 | | [Optimizing Context Usage](optimizing-context-usage.md) | Context compression techniques | Technical details of algorithms used to optimize context window utilization | 29 | | [Rooignore Configuration](rooignore-configuration.md) | Gitignore-style pattern implementation | Explains how .rooignore patterns are parsed, cached, and applied to file operations | 30 | | [Task Management](task-management.md) | Conversation session architecture | Technical details of how Roo manages separate conversation sessions and their state | 31 | -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/README.md: -------------------------------------------------------------------------------- 1 | # Handoff Publisher 2 | 3 | A modular package for generating the Handoff Manager installer. 4 | 5 | ## Overview 6 | 7 | The Handoff Publisher is a Node.js package that generates a standalone installer for the Handoff Manager system. It follows a configuration-driven approach where: 8 | 9 | 1. The `publish-config.json` specifies which files to include 10 | 2. The `system-prompt-config.json` defines how to assemble the system prompt 11 | 12 | This modular approach allows evolution of the handoff system without modifying the publisher code. 13 | 14 | ## Directory Structure 15 | 16 | ``` 17 | handoff-publisher/ 18 | ├── config/ 19 | │ └── publish-config.json # Configuration for the publisher 20 | ├── lib/ 21 | │ ├── file-utils.js # File operation utilities 22 | │ ├── config-merger.js # Handles merging of configuration files 23 | │ ├── system-prompt.js # Assembles the system prompt 24 | │ └── installer-generator.js # Generates the installer script 25 | ├── index.js # Main entry point 26 | ├── package.json # Package metadata 27 | └── README.md # This file 28 | ``` 29 | 30 | ## Usage 31 | 32 | From the handoff-system directory: 33 | 34 | ```bash 35 | cd handoff-publisher 36 | npm install 37 | node index.js [output-file-path] 38 | ``` 39 | 40 | If no output file path is provided, it will use the path specified in `config/publish-config.json`. 41 | 42 | ## Configuration 43 | 44 | The `publish-config.json` file contains the following settings: 45 | 46 | - `name`: Name of the handoff manager 47 | - `version`: Version number 48 | - `description`: Description of the handoff manager 49 | - `outputFile`: Path to the output installer file 50 | - `sourceDir`: Source directory for files 51 | - `rootFiles`: Array of root files to include 52 | - `directories`: Array of directory configurations 53 | - `components`: Configuration for system prompt components 54 | - `maxFileSize`: Maximum file size to include 55 | - `installOptions`: Installation options 56 | - `nextSteps`: Array of next steps to display after installation 57 | - `documentation`: Array of documentation files 58 | 59 | ## Key Features 60 | 61 | 1. **Modular Architecture**: Split into logical components for better maintainability 62 | 2. **Configuration-Driven**: Uses JSON configuration files for flexibility 63 | 3. **Improved File Handling**: Better handling of existing files during installation 64 | 4. **Robust Error Handling**: Comprehensive error handling and recovery mechanisms 65 | 5. **Detailed Logging**: Verbose logging for easier troubleshooting 66 | 67 | ## Installer Features 68 | 69 | The generated installer includes these key features: 70 | 71 | - **Existing Installation Detection**: Automatically detects and backs up any existing handoff system files 72 | - **Configuration Merging**: Preserves existing custom modes when adding handoff-manager mode 73 | - **Complete System**: Contains all necessary files to get started immediately 74 | - **Self-contained**: No external dependencies required 75 | 76 | ## Maintenance 77 | 78 | To update the handoff system: 79 | 80 | 1. Modify the files in the handoff-system directory 81 | 2. Update the `publish-config.json` if necessary 82 | 3. Run the publisher to generate a new installer 83 | 84 | This approach allows for easy updates without modifying the publisher code. -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/docs/component-sets-specification.md: -------------------------------------------------------------------------------- 1 | # Component Sets Specification 2 | 3 | ## Overview 4 | 5 | The Handoff Publisher system uses a component-based architecture for modular, maintainable code. This specification defines how to create and use component sets within the publisher. 6 | 7 | ## What is a Component Set? 8 | 9 | A component set is a collection of files that work together to provide specific functionality. Each component set: 10 | 11 | 1. Has a dedicated directory 12 | 2. Contains numbered component files (e.g., `1-utils.js`, `2-backup.js`) 13 | 3. Includes a configuration file (e.g., `src-config.json`, `system-prompt-config.json`) 14 | 4. Is defined in `publish-config.json` under the `componentSets` array 15 | 16 | ## Creating a New Component Set 17 | 18 | To create a new component set: 19 | 20 | 1. Create a dedicated directory for your components 21 | 2. Create numbered component files with clear names 22 | 3. Create a configuration file for the component set 23 | 4. Add the component set to the `componentSets` array in `publish-config.json` 24 | 25 | ### Component Naming Convention 26 | 27 | Components should follow this naming convention: 28 | - Prefix with a number to indicate loading order 29 | - Use descriptive names for the functionality 30 | - Example: `1-utils.js`, `2-processor.js`, `3-formatter.js` 31 | 32 | ### Configuration File Structure 33 | 34 | Each component set needs a configuration file with this structure: 35 | 36 | ```json 37 | { 38 | "components": [ 39 | { 40 | "file": "1-component.js", 41 | "description": "Description of the component's functionality" 42 | }, 43 | { 44 | "file": "2-component.js", 45 | "description": "Description of the component's functionality" 46 | } 47 | ], 48 | "version": "1.0.0", 49 | "errorHandling": { 50 | "missingFile": "error", 51 | "continueOnError": false 52 | } 53 | } 54 | ``` 55 | 56 | ### Adding to publish-config.json 57 | 58 | Add your component set to the `componentSets` array in `publish-config.json`: 59 | 60 | ```json 61 | "componentSets": [ 62 | { 63 | "type": "your-component-type", 64 | "sourcePath": "path/to/components", 65 | "configFile": "your-config.json" 66 | } 67 | ] 68 | ``` 69 | 70 | ## Existing Component Sets 71 | 72 | The system currently includes two component sets: 73 | 74 | 1. **system-prompt**: Assembles the system prompt from component files 75 | - Location: `1-handoff-custom-mode/components` 76 | - Config: `system-prompt-config.json` 77 | 78 | 2. **source-code**: Contains modular source code functions for the installer 79 | - Location: `handoff-publisher/lib/src` 80 | - Config: `src-config.json` 81 | 82 | ## Loading and Processing Components 83 | 84 | Components are loaded and processed in the order specified in their configuration file. The publisher framework: 85 | 86 | 1. Reads the component set configuration 87 | 2. Loads each component in the specified order 88 | 3. Processes the components according to their type 89 | 4. Integrates the processed components into the final output 90 | 91 | ## Best Practices 92 | 93 | 1. Keep components small and focused on a single responsibility 94 | 2. Use meaningful numbering to indicate dependencies and loading order 95 | 3. Include a detailed description for each component 96 | 4. Handle errors appropriately in the configuration 97 | 5. Test components individually and as part of the whole system -------------------------------------------------------------------------------- /handoff-system/1-handoff-custom-mode/README.md: -------------------------------------------------------------------------------- 1 | # Handoff Manager System Components 2 | 3 | This directory contains the Markdown component files used to construct the Handoff Manager system prompt. Using Markdown instead of plain text makes the components more structured and readable, with enhanced formatting capabilities for better explanation of concepts. 4 | 5 | ## Structure 6 | 7 | The system uses the following structure: 8 | 9 | ``` 10 | .roo/ 11 | └── components/ # System prompt Markdown components 12 | ├── header.md # Basic role definition 13 | ├── directory-detection.md 14 | ├── restoration-flowchart.md 15 | ├── creation-flowchart.md 16 | ├── handoff-creation.md 17 | ├── milestone-creation.md 18 | ├── session-restoration.md 19 | ├── conversation-extraction.md 20 | ├── numbering-logic.md 21 | └── safety-rules.md 22 | ``` 23 | 24 | ## Component Details 25 | 26 | Each Markdown component serves a specific purpose in the overall system: 27 | 28 | | Component | Purpose | 29 | |-----------|---------| 30 | | `header.md` | Defines the basic role and responsibilities | 31 | | `directory-detection.md` | Logic for finding/creating handoff directories | 32 | | `restoration-flowchart.md` | Visual workflow for session restoration | 33 | | `creation-flowchart.md` | Visual workflow for handoff/milestone creation | 34 | | `handoff-creation.md` | Detailed structure and requirements for handoffs | 35 | | `milestone-creation.md` | Procedures for milestone creation | 36 | | `session-restoration.md` | Process for restoring context from documents | 37 | | `conversation-extraction.md` | Integration with conversation analysis | 38 | | `numbering-logic.md` | Robust sequential numbering procedures | 39 | | `safety-rules.md` | Error prevention and safety guidelines | 40 | 41 | ## Markdown Benefits 42 | 43 | Using Markdown for the components provides several advantages: 44 | 45 | 1. **Enhanced Formatting**: Tables, lists, and headers make information more structured 46 | 2. **Visual Elements**: Flowcharts and diagrams rendered through Mermaid 47 | 3. **Code Blocks**: Properly formatted code examples with syntax highlighting 48 | 4. **Callouts**: Important notes, warnings, and best practices are visually distinct 49 | 5. **Better Readability**: Both for humans reviewing the components and the LLM interpreting them 50 | 51 | ## Assembly Process 52 | 53 | The `create-handoff-manager.js` script in the parent directory assembles these Markdown components into a single system prompt file. The components are assembled in a specific order to ensure proper context and flow. 54 | 55 | ## Modification Guidelines 56 | 57 | When modifying components: 58 | 59 | 1. **Independent Changes**: Each component can be modified independently without affecting others 60 | 2. **Cross-References**: Be careful about cross-referencing between components 61 | 3. **Assembly Order**: The order of components matters - they build on one another 62 | 4. **Run the Generator**: After any changes, run `node create-handoff-manager.js` to rebuild the system prompt 63 | 5. **Markdown Formatting**: Leverage Markdown features to make the content more understandable 64 | 65 | ## Adding New Components 66 | 67 | To add a new component: 68 | 69 | 1. Create a new Markdown file in the components directory 70 | 2. Add the component name to the `componentFiles` array in `create-handoff-manager.js` 71 | 3. Run the generator script to incorporate the new component -------------------------------------------------------------------------------- /handoff-system/1-handoff-custom-mode/components/5-creation-flowchart.md: -------------------------------------------------------------------------------- 1 | 2 | ==== 3 | 4 | # Handoff Creation Workflow 5 | 6 | Follow this detailed workflow diagram when creating handoffs or milestones: 7 | 8 | ```mermaid 9 | graph TD 10 | Start[Begin Handoff Process] --> CheckEligibility{Is Handoff
Needed?} 11 | CheckEligibility -->|No| SuggestContinue[Suggest Continuing
Current Work] 12 | SuggestContinue --> End 13 | 14 | CheckEligibility -->|Yes| CheckExtraction{Conversation
Extract Available?} 15 | 16 | CheckExtraction -->|Yes| ProcessExtract[Process Conversation
Extract] 17 | CheckExtraction -->|No| SkipExtract[Continue Without
Conversation Extract] 18 | 19 | ProcessExtract --> ExamineDirectory[Examine Handoff
Directory Structure] 20 | SkipExtract --> ExamineDirectory 21 | 22 | ExamineDirectory --> CheckFiles{Root Handoff
Files Exist?} 23 | 24 | CheckFiles -->|Yes| CountHandoffs[Count Existing
Handoff Documents] 25 | CheckFiles -->|No| CreateFirst[Create First
Handoff Document] 26 | CreateFirst --> End 27 | 28 | CountHandoffs --> CheckMilestone{3-5 Handoffs
Accumulated?} 29 | 30 | CheckMilestone -->|No| CreateHandoff[Create Next
Sequential Handoff] 31 | CreateHandoff --> End 32 | 33 | CheckMilestone -->|Yes| SuggestMilestone[Suggest Creating
Milestone] 34 | SuggestMilestone --> UserResponse{User Wants
Milestone?} 35 | 36 | UserResponse -->|No| CreateHandoff 37 | UserResponse -->|Yes| VerifyFinalHandoff{Recent Final
Handoff Exists?} 38 | 39 | VerifyFinalHandoff -->|No| CreateFinalHandoff[Create Final Handoff
Before Milestone] 40 | VerifyFinalHandoff -->|Yes| CalculateNextNumber[Calculate Next
Milestone Number] 41 | 42 | CreateFinalHandoff --> CalculateNextNumber 43 | 44 | CalculateNextNumber --> CreateMilestoneDir[Create Milestone
Directory] 45 | CreateMilestoneDir --> MoveHandoffs[Move Handoff Files
to Milestone Dir] 46 | MoveHandoffs --> CreateSummary[Create Milestone
Summary & Lessons] 47 | CreateSummary --> CleanupReminders[Remind About
Next Steps] 48 | CleanupReminders --> End[Process Complete] 49 | ``` 50 | 51 | ## Creation Decision Points 52 | 53 | At each decision point in the workflow: 54 | 55 | ### 1. Handoff Eligibility Check 56 | Evaluate if a handoff is needed based on criteria: 57 | 58 | | Criteria | Description | 59 | |----------|-------------| 60 | | Context Relevance | Context becomes ~30% irrelevant to current task | 61 | | Project Progress | Completing significant project segments | 62 | | Conversation Length | After 10+ conversation exchanges | 63 | | Debugging Duration | During debugging sessions exceeding 5 exchanges without resolution | 64 | 65 | ### 2. Conversation Extract Processing 66 | If a conversation extract is available, analyze it to identify: 67 | - Discoveries made 68 | - Problems and solutions 69 | - Work in progress 70 | 71 | > **Note:** This is optional - proceed without it if not available 72 | 73 | ### 3. Directory Structure Analysis 74 | - Examine the handoff directory to determine the next steps 75 | - Check if it's a brand new setup or existing structure 76 | - Identify milestone directories and handoff files 77 | 78 | ### 4. Milestone Recommendation 79 | - After 3-5 handoffs accumulate, suggest creating a milestone 80 | - The user makes the final decision on whether to proceed 81 | 82 | > **Best Practice:** Always create a final handoff before creating a milestone to ensure all recent work is captured. -------------------------------------------------------------------------------- /roo-ignore/README.md: -------------------------------------------------------------------------------- 1 | # Roo-Ignore Generator 2 | 3 | A utility script that automatically generates and updates `.rooignore` files to prevent LLM context overflow while preserving your custom content. 4 | 5 | ## Overview 6 | 7 | 1. Identifying files that exceed your specified token threshold 8 | 2. Adding minimal patterns for binary file types that wouldn't be useful to the LLM 9 | 3. Preserving existing content and custom patterns in your `.rooignore` file 10 | 11 | This ensures Roo-Code's LLM can operate efficiently without context overflow issues, while respecting your specific project needs. 12 | 13 | ## Installation 14 | 15 | Generally you want to put this file in the project root and run it. If you are using bash you can use wget 16 | ```bash 17 | wget https://raw.githubusercontent.com/Michaelzag/RooCode-Tips-Tricks/main/roo-ignore/generate-rooignore.js 18 | ``` 19 | then: 20 | 21 | ```bash 22 | node generate-rooignore.js node generate-rooignore.js --threshold=30000 23 | ``` 24 | 25 | if it doensm't work you might need to chmod +x 26 | 27 | ## Advanced Usage 28 | 29 | ```bash 30 | node generate-rooignore.js [directory] [--threshold=NUMBER] 31 | ``` 32 | 33 | ### Options 34 | 35 | - `[directory]` - The directory to analyze (defaults to current directory) 36 | - `--threshold=NUMBER` - Set custom token threshold (default: 45000) 37 | - `--help` - Show help information 38 | 39 | ### Examples 40 | 41 | ```bash 42 | # Generate for current directory with default threshold (45k tokens) 43 | node generate-rooignore.js 44 | 45 | # Set a custom threshold 46 | node generate-rooignore.js --threshold=30000 47 | 48 | # Generate for a specific directory 49 | node generate-rooignore.js ./my-project 50 | 51 | # Display help information 52 | node generate-rooignore.js --help 53 | ``` 54 | 55 | ## Features 56 | 57 | ### Token Estimation 58 | 59 | The script uses a simple estimation method: 60 | - Approximately 4 characters ≈ 1 token 61 | - Binary files are auto-detected and handled appropriately 62 | 63 | ### Smart Skipping for Efficient Scanning 64 | 65 | - Skips only essential directories like `.git`, `venv`, `node_modules` during scanning. There should be no readon the llm should be accessing these folders anyhow. 66 | - Uses insights from .gitignore to identify additional directories to skip 67 | - Only skips directories when scanning, not in the final ignore patterns 68 | 69 | ### Minimal Ignore Patterns 70 | 71 | - Only adds large files that exceed your token threshold 72 | - Includes minimal binary file patterns that are definitely not useful to an LLM 73 | 74 | ### Preserving Custom Content 75 | 76 | The script is designed to preserve your custom modifications: 77 | - Only updates the large files section of existing .rooignore files 78 | - Maintains your custom patterns and structure 79 | - Adds new large files when detected 80 | 81 | ## How It Works 82 | 83 | 1. Scans files in the target directory (skipping specific directories for efficiency) 84 | 2. Estimates token count for each file 85 | 3. Identifies files exceeding the specified threshold 86 | 4. Intelligently updates or creates a .rooignore file 87 | 88 | ## Best Practices 89 | 90 | - Run periodically after adding new large files to projects 91 | - Set an appropriate threshold based on your LLM's context window (45k is a good default) 92 | - Review the .rooignore file after generation to ensure it meets your needs 93 | - Consider adding custom patterns for your specific project needs 94 | - Review generated files to ensure they don't block important project files 95 | 96 | ## License 97 | 98 | This script is provided as-is for use with Roo-Code. -------------------------------------------------------------------------------- /handoff-manager/handoffs/0-system/scripts/README.md: -------------------------------------------------------------------------------- 1 | # Handoff System Scripts 2 | 3 | This directory contains scripts to automate common tasks in the Handoff System. These scripts help with installing the system, creating milestones, and managing handoff documents. 4 | 5 | ## Installation Script 6 | 7 | ### install-handoff-manager.js 8 | 9 | Installs the Handoff Manager in a project, preserving any existing configurations. 10 | 11 | ```bash 12 | node install-handoff-manager.js [target-directory] 13 | ``` 14 | 15 | - If `target-directory` is not specified, it installs to the current directory. 16 | - Merges with existing .roomodes and .clinerules files if they exist. 17 | - Creates necessary directories and copies all required files. 18 | 19 | ## Conversation Extraction 20 | 21 | ### extract-conversation.js 22 | 23 | Processes an exported conversation file to create a clean version for handoff creation. This script combines both Python and JavaScript approaches for maximum compatibility. 24 | 25 | ```bash 26 | node extract-conversation.js [handoffs_dir] 27 | ``` 28 | 29 | The script: 30 | 1. Determines the next handoff number 31 | 2. Names the output file `-chat_transcript.md` (e.g., `4-chat_transcript.md`) 32 | 3. First tries the Python extraction script 33 | 4. Falls back to the JavaScript extraction script if Python fails 34 | 5. Saves the result in the handoffs directory 35 | 36 | This ensures the conversation extract is available for the handoff manager to use when creating handoff documents. 37 | 38 | ## Milestone Scripts 39 | 40 | These scripts automate the creation of milestone directories and the movement of handoff files: 41 | 42 | ### create-milestone-bash.sh (Bash/Unix) 43 | 44 | ```bash 45 | ./create-milestone-bash.sh [milestone-name] 46 | ``` 47 | 48 | ### create-milestone-powershell.ps1 (PowerShell/Windows) 49 | 50 | ```powershell 51 | .\create-milestone-powershell.ps1 [milestone-name] 52 | ``` 53 | 54 | ### create-milestone.py (Python - Cross-platform) 55 | 56 | ```bash 57 | python create-milestone.py [milestone-name] 58 | ``` 59 | 60 | ### create-milestone.js (Node.js - Cross-platform) 61 | 62 | ```bash 63 | node create-milestone.js [milestone-name] 64 | ``` 65 | 66 | Each script performs the following steps: 67 | 68 | 1. Calculates the next sequential milestone number 69 | 2. Creates a new milestone directory with the pattern `N-milestone-name` 70 | 3. Moves all handoff documents (numbered .md files) from the handoffs root directory to the milestone directory 71 | 4. Provides a reminder to create the required summary documents 72 | 73 | ## Script Selection Guide 74 | 75 | | Environment | Preferred Script | 76 | |-------------|-----------------| 77 | | Linux/macOS | create-milestone-bash.sh | 78 | | Windows PowerShell | create-milestone-powershell.ps1 | 79 | | Python installed | create-milestone.py | 80 | | Node.js installed | create-milestone.js | 81 | 82 | For conversation extraction, the combined `extract-conversation.js` script is designed to work in all environments by trying Python first, then falling back to Node.js if needed. 83 | 84 | ## Usage within Handoff Manager 85 | 86 | The Handoff Manager can execute these scripts directly. For example: 87 | 88 | ``` 89 | I need to create a milestone for our completed feature. Please run the appropriate milestone script based on my environment. 90 | ``` 91 | 92 | ``` 93 | I need to extract the key insights from our conversation history at conversation.md. Please run the extract-conversation.js script. 94 | ``` 95 | 96 | The handoff manager will detect your environment and choose the most appropriate script to execute. -------------------------------------------------------------------------------- /handoffs/0-instructions/2-milestone-instructions.md: -------------------------------------------------------------------------------- 1 | # Milestone System 2 | 3 | ## Purpose 4 | Record milestones when: 5 | - Major component completed 6 | - Critical bug fixed 7 | - Implementation changed 8 | - Feature delivered 9 | 10 | ## Core Principles 11 | - **Concise**: Every token counts 12 | - **Factual**: Concrete details, not stories 13 | - **Relevant**: Include essential only 14 | - **Future-Focused**: What next devs need 15 | - **Learning**: Document issues and solutions 16 | 17 | ## Handoff to Milestone 18 | 1. **Create Handoffs First**: 19 | - Write handoffs during development 20 | - Capture work completed in each session 21 | - Accumulate in handoffs/ directory 22 | - Use sequential numbering (1-setup.md, 2-entities.md) 23 | 24 | 2. **Distill to Milestones**: 25 | - Extract key info from handoffs 26 | - Identify patterns across handoffs 27 | - Consolidate repeated themes 28 | - Transform details into concise facts 29 | - Prioritize long-term value info 30 | 31 | ## Workflow 32 | 1. **Development with Handoffs**: 33 | - Document work in handoff files 34 | - Progress through sequential handoffs 35 | - Handoffs accumulate in handoffs/ directory 36 | 37 | 2. **At milestone**: 38 | - Create milestone folder with descriptive name 39 | - Use sequential numbers (1-feature, 2-api, etc.) 40 | - Distill handoffs into milestone docs 41 | - Move docs to milestone folder 42 | - Name reflects actual achievement 43 | 44 | ## Files 45 | 1. **0-milestone-summary.md**: 46 | - Date completed 47 | - Changes implemented 48 | - Decisions made and why 49 | - Discoveries found 50 | - Current system state 51 | 52 | 2. **0-lessons-learned.md**: 53 | - Problems encountered 54 | - Working solutions 55 | - Tools/libraries used 56 | - Edge cases identified 57 | - Reusable patterns 58 | 59 | ## Naming Convention 60 | - System files: prefix with "0-" (0-milestone-summary.md) 61 | - Handoffs: numbered without "0-" (1-setup.md) 62 | - Milestone folders: numbered without "0-" (1-feature) 63 | 64 | ## Writing Style 65 | 66 | ### 0-milestone-summary.md 67 | ``` 68 | ## Changes 69 | - Data connector with batch processing 70 | - Optimized query approach (30x faster) 71 | - Cross-platform path handling 72 | 73 | ## Decisions 74 | - Validation library update: 40% faster 75 | - Nested env vars for configuration 76 | - Default fallback for missing references 77 | 78 | ## Discoveries 79 | - Duplicate entities: Item A has IDs 64, 125 80 | - Relationship gaps: 246/252 entities connected 81 | - Missing refs: IDs 53, 54 not in dataset 82 | ``` 83 | 84 | ### 0-lessons-learned.md 85 | ``` 86 | ## Config Library Migration 87 | 88 | **Problem:** `Cannot import Settings from library` 89 | 90 | **Solution:** 91 | - Update dependency version 92 | - Use new config pattern 93 | - Update initialization with correct prefix 94 | 95 | ## Null Value Handling 96 | 97 | **Problem:** `Invalid value in transformation` 98 | 99 | **Solution:** 100 | - Create sanitization function 101 | - Replace invalid values with null 102 | - Apply to all values before serialization 103 | ``` 104 | 105 | ## Example 106 | Before: 3 handoff files 107 | ``` 108 | handoffs/1-api-setup.md 109 | handoffs/2-core-entities-implementation.md 110 | handoffs/3-relationship-fixes.md 111 | ``` 112 | 113 | After: 114 | ``` 115 | handoffs/ (continues to accumulate new handoffs) 116 | 117 | handoffs/1-core-entities/ 118 | ├── 0-milestone-summary.md # Decisions, discoveries 119 | └── 0-lessons-learned.md # Patterns, fixes -------------------------------------------------------------------------------- /handoff-system/handoff-publisher/node_modules/fs-extra/lib/ensure/symlink-paths.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const path = require('path') 4 | const fs = require('../fs') 5 | const { pathExists } = require('../path-exists') 6 | 7 | const u = require('universalify').fromPromise 8 | 9 | /** 10 | * Function that returns two types of paths, one relative to symlink, and one 11 | * relative to the current working directory. Checks if path is absolute or 12 | * relative. If the path is relative, this function checks if the path is 13 | * relative to symlink or relative to current working directory. This is an 14 | * initiative to find a smarter `srcpath` to supply when building symlinks. 15 | * This allows you to determine which path to use out of one of three possible 16 | * types of source paths. The first is an absolute path. This is detected by 17 | * `path.isAbsolute()`. When an absolute path is provided, it is checked to 18 | * see if it exists. If it does it's used, if not an error is returned 19 | * (callback)/ thrown (sync). The other two options for `srcpath` are a 20 | * relative url. By default Node's `fs.symlink` works by creating a symlink 21 | * using `dstpath` and expects the `srcpath` to be relative to the newly 22 | * created symlink. If you provide a `srcpath` that does not exist on the file 23 | * system it results in a broken symlink. To minimize this, the function 24 | * checks to see if the 'relative to symlink' source file exists, and if it 25 | * does it will use it. If it does not, it checks if there's a file that 26 | * exists that is relative to the current working directory, if does its used. 27 | * This preserves the expectations of the original fs.symlink spec and adds 28 | * the ability to pass in `relative to current working direcotry` paths. 29 | */ 30 | 31 | async function symlinkPaths (srcpath, dstpath) { 32 | if (path.isAbsolute(srcpath)) { 33 | try { 34 | await fs.lstat(srcpath) 35 | } catch (err) { 36 | err.message = err.message.replace('lstat', 'ensureSymlink') 37 | throw err 38 | } 39 | 40 | return { 41 | toCwd: srcpath, 42 | toDst: srcpath 43 | } 44 | } 45 | 46 | const dstdir = path.dirname(dstpath) 47 | const relativeToDst = path.join(dstdir, srcpath) 48 | 49 | const exists = await pathExists(relativeToDst) 50 | if (exists) { 51 | return { 52 | toCwd: relativeToDst, 53 | toDst: srcpath 54 | } 55 | } 56 | 57 | try { 58 | await fs.lstat(srcpath) 59 | } catch (err) { 60 | err.message = err.message.replace('lstat', 'ensureSymlink') 61 | throw err 62 | } 63 | 64 | return { 65 | toCwd: srcpath, 66 | toDst: path.relative(dstdir, srcpath) 67 | } 68 | } 69 | 70 | function symlinkPathsSync (srcpath, dstpath) { 71 | if (path.isAbsolute(srcpath)) { 72 | const exists = fs.existsSync(srcpath) 73 | if (!exists) throw new Error('absolute srcpath does not exist') 74 | return { 75 | toCwd: srcpath, 76 | toDst: srcpath 77 | } 78 | } 79 | 80 | const dstdir = path.dirname(dstpath) 81 | const relativeToDst = path.join(dstdir, srcpath) 82 | const exists = fs.existsSync(relativeToDst) 83 | if (exists) { 84 | return { 85 | toCwd: relativeToDst, 86 | toDst: srcpath 87 | } 88 | } 89 | 90 | const srcExists = fs.existsSync(srcpath) 91 | if (!srcExists) throw new Error('relative srcpath does not exist') 92 | return { 93 | toCwd: srcpath, 94 | toDst: path.relative(dstdir, srcpath) 95 | } 96 | } 97 | 98 | module.exports = { 99 | symlinkPaths: u(symlinkPaths), 100 | symlinkPathsSync 101 | } 102 | -------------------------------------------------------------------------------- /handoff-system/handoff-installer-readme.md: -------------------------------------------------------------------------------- 1 | # Handoff Manager Installer 2 | 3 | This directory contains a standalone installer script for the Handoff Manager system. 4 | 5 | ## Overview 6 | 7 | The `handoff-manager-installer.js` is a self-contained script that installs the complete Handoff Manager system into any project directory. It includes all necessary files and configurations without requiring any external dependencies. 8 | 9 | ## What Gets Installed 10 | 11 | When you run the installer, it will create: 12 | 13 | - Custom mode configuration in `.roomodes` 14 | - Handoff system rules in `.clinerules` 15 | - System prompt for the Handoff Manager 16 | - Directory structure for handoffs: 17 | - `handoffs/0-instructions/` - Documentation for the handoff system 18 | - `handoffs/scripts/` - Utility scripts for handoff management 19 | 20 | ## Handoff Manager Custom Mode 21 | 22 | The installer adds a dedicated "Handoff Manager" custom mode to your Roo environment, which: 23 | 24 | - Provides specialized capabilities for managing project handoffs and milestones 25 | - Has permission to create and edit files in the handoffs directory 26 | - Follows structured workflows for creating handoffs, milestones, and restoring sessions 27 | - Can access conversation history to enhance handoff content 28 | - Uses a comprehensive system prompt with diagrams and structured processes 29 | 30 | ## Usage 31 | 32 | Run the installer from the command line in your project's root directory: 33 | 34 | ```bash 35 | node handoff-manager-installer.js 36 | ``` 37 | 38 | This will install the Handoff Manager system into your current directory. 39 | 40 | > **IMPORTANT**: The installer MUST be run from your project's root directory where your .roomodes and .clinerules files are located. The Handoff Manager is designed to work alongside your existing Roo configuration. 41 | > 42 | > **Project Root Requirement**: This is critical because the installer needs to find and modify your project's configuration files. Running it in any other directory will result in an incomplete installation. 43 | 44 | ### Advanced Usage 45 | 46 | If you need to install to a specific project directory: 47 | 48 | ```bash 49 | node handoff-manager-installer.js 50 | ``` 51 | 52 | #### Examples 53 | 54 | Install to a specific project root: 55 | ```bash 56 | node handoff-manager-installer.js ../my-project 57 | ``` 58 | 59 | Install to a parent project: 60 | ```bash 61 | node handoff-manager-installer.js .. 62 | ``` 63 | 64 | > **Note**: Wherever you install, that location must be a project root with access to .roomodes and .clinerules files. 65 | 66 | ## Features 67 | 68 | - **Existing Installation Detection**: Automatically detects and backs up any existing handoff system files 69 | - **Configuration Merging**: Preserves your existing custom modes when adding handoff-manager mode 70 | - **Complete System**: Contains all necessary files to get started immediately 71 | - **Self-contained**: No external dependencies required 72 | 73 | ## After Installation 74 | 75 | Once installed, you can: 76 | 77 | 1. Switch to handoff-manager mode in Roo-Code 78 | 2. Create your first handoff with: 79 | ``` 80 | I need to create a handoff document for our current work. Please follow the handoff creation workflow. 81 | ``` 82 | 3. Delete the handoff-manager-installer.js. It's generally too big to be read by LLM's. If they read it on accident it will overflow the context. 83 | 84 | ## Requirements 85 | 86 | - **Node.js**: This installer requires Node.js to be installed on your system (any recent version) 87 | - A project directory where you want to add handoff management capabilities 88 | 89 | ## Troubleshooting 90 | 91 | - **File Permission Issues**: If you encounter permission errors, ensure you have write access to the target directory 92 | - **Existing Files**: The installer will safely back up existing files, but check the backup directory if you need to recover previous versions 93 | 94 | For more information about using the Handoff Manager itself, refer to the documentation in `handoffs/0-instructions/` after installation. -------------------------------------------------------------------------------- /single-script/handoff-installer-readme.md: -------------------------------------------------------------------------------- 1 | # Handoff Manager Installer 2 | 3 | This directory contains a standalone installer script for the Handoff Manager system. 4 | 5 | ## Overview 6 | 7 | The `handoff-manager-installer.js` is a self-contained script that installs the complete Handoff Manager system into any project directory. It includes all necessary files and configurations without requiring any external dependencies. 8 | 9 | ## What Gets Installed 10 | 11 | When you run the installer, it will create: 12 | 13 | - Custom mode configuration in `.roomodes` 14 | - Handoff system rules in `.clinerules` 15 | - System prompt for the Handoff Manager 16 | - Directory structure for handoffs: 17 | - `handoffs/0-instructions/` - Documentation for the handoff system 18 | - `handoffs/scripts/` - Utility scripts for handoff management 19 | 20 | ## Handoff Manager Custom Mode 21 | 22 | The installer adds a dedicated "Handoff Manager" custom mode to your Roo environment, which: 23 | 24 | - Provides specialized capabilities for managing project handoffs and milestones 25 | - Has permission to create and edit files in the handoffs directory 26 | - Follows structured workflows for creating handoffs, milestones, and restoring sessions 27 | - Can access conversation history to enhance handoff content 28 | - Uses a comprehensive system prompt with diagrams and structured processes 29 | 30 | ## Usage 31 | 32 | Run the installer from the command line in your project's root directory: 33 | 34 | ```bash 35 | node handoff-manager-installer.js 36 | ``` 37 | 38 | This will install the Handoff Manager system into your current directory. 39 | 40 | > **IMPORTANT**: The installer MUST be run from your project's root directory where your .roomodes and .clinerules files are located. The Handoff Manager is designed to work alongside your existing Roo configuration. 41 | > 42 | > **Project Root Requirement**: This is critical because the installer needs to find and modify your project's configuration files. Running it in any other directory will result in an incomplete installation. 43 | 44 | ### Advanced Usage 45 | 46 | If you need to install to a specific project directory: 47 | 48 | ```bash 49 | node handoff-manager-installer.js 50 | ``` 51 | 52 | #### Examples 53 | 54 | Install to a specific project root: 55 | ```bash 56 | node handoff-manager-installer.js ../my-project 57 | ``` 58 | 59 | Install to a parent project: 60 | ```bash 61 | node handoff-manager-installer.js .. 62 | ``` 63 | 64 | > **Note**: Wherever you install, that location must be a project root with access to .roomodes and .clinerules files. 65 | 66 | ## Features 67 | 68 | - **Existing Installation Detection**: Automatically detects and backs up any existing handoff system files 69 | - **Configuration Merging**: Preserves your existing custom modes when adding handoff-manager mode 70 | - **Complete System**: Contains all necessary files to get started immediately 71 | - **Self-contained**: No external dependencies required 72 | 73 | ## After Installation 74 | 75 | Once installed, you can: 76 | 77 | 1. Switch to handoff-manager mode in Roo-Code 78 | 2. Create your first handoff with: 79 | ``` 80 | I need to create a handoff document for our current work. Please follow the handoff creation workflow. 81 | ``` 82 | 3. Delete the handoff-manager-installer.js. It's generally too big to be read by LLM's. If they read it on accident it will overflow the context. 83 | 84 | ## Requirements 85 | 86 | - **Node.js**: This installer requires Node.js to be installed on your system (any recent version) 87 | - A project directory where you want to add handoff management capabilities 88 | 89 | ## Troubleshooting 90 | 91 | - **File Permission Issues**: If you encounter permission errors, ensure you have write access to the target directory 92 | - **Existing Files**: The installer will safely back up existing files, but check the backup directory if you need to recover previous versions 93 | 94 | For more information about using the Handoff Manager itself, refer to the documentation in `handoffs/0-instructions/` after installation. -------------------------------------------------------------------------------- /handoff-manager/single-script/handoff-installer-readme.md: -------------------------------------------------------------------------------- 1 | # Handoff Manager Installer 2 | 3 | This directory contains a standalone installer script for the Handoff Manager system. 4 | 5 | ## Overview 6 | 7 | The `handoff-manager-installer.js` is a self-contained script that installs the complete Handoff Manager system into any project directory. It includes all necessary files and configurations without requiring any external dependencies. 8 | 9 | ## What Gets Installed 10 | 11 | When you run the installer, it will create: 12 | 13 | - Custom mode configuration in `.roomodes` 14 | - Handoff system rules in `.clinerules` 15 | - System prompt for the Handoff Manager 16 | - Directory structure for handoffs: 17 | - `handoffs/0-instructions/` - Documentation for the handoff system 18 | - `handoffs/scripts/` - Utility scripts for handoff management 19 | 20 | ## Handoff Manager Custom Mode 21 | 22 | The installer adds a dedicated "Handoff Manager" custom mode to your Roo environment, which: 23 | 24 | - Provides specialized capabilities for managing project handoffs and milestones 25 | - Has permission to create and edit files in the handoffs directory 26 | - Follows structured workflows for creating handoffs, milestones, and restoring sessions 27 | - Can access conversation history to enhance handoff content 28 | - Uses a comprehensive system prompt with diagrams and structured processes 29 | 30 | ## Usage 31 | 32 | Run the installer from the command line in your project's root directory: 33 | 34 | ```bash 35 | node handoff-manager-installer.js 36 | ``` 37 | 38 | This will install the Handoff Manager system into your current directory. 39 | 40 | > **IMPORTANT**: The installer MUST be run from your project's root directory where your .roomodes and .clinerules files are located. The Handoff Manager is designed to work alongside your existing Roo configuration. 41 | > 42 | > **Project Root Requirement**: This is critical because the installer needs to find and modify your project's configuration files. Running it in any other directory will result in an incomplete installation. 43 | 44 | ### Advanced Usage 45 | 46 | If you need to install to a specific project directory: 47 | 48 | ```bash 49 | node handoff-manager-installer.js 50 | ``` 51 | 52 | #### Examples 53 | 54 | Install to a specific project root: 55 | ```bash 56 | node handoff-manager-installer.js ../my-project 57 | ``` 58 | 59 | Install to a parent project: 60 | ```bash 61 | node handoff-manager-installer.js .. 62 | ``` 63 | 64 | > **Note**: Wherever you install, that location must be a project root with access to .roomodes and .clinerules files. 65 | 66 | ## Features 67 | 68 | - **Existing Installation Detection**: Automatically detects and backs up any existing handoff system files 69 | - **Configuration Merging**: Preserves your existing custom modes when adding handoff-manager mode 70 | - **Complete System**: Contains all necessary files to get started immediately 71 | - **Self-contained**: No external dependencies required 72 | 73 | ## After Installation 74 | 75 | Once installed, you can: 76 | 77 | 1. Switch to handoff-manager mode in Roo-Code 78 | 2. Create your first handoff with: 79 | ``` 80 | I need to create a handoff document for our current work. Please follow the handoff creation workflow. 81 | ``` 82 | 3. Delete the handoff-manager-installer.js. It's generally too big to be read by LLM's. If they read it on accident it will overflow the context. 83 | 84 | ## Requirements 85 | 86 | - **Node.js**: This installer requires Node.js to be installed on your system (any recent version) 87 | - A project directory where you want to add handoff management capabilities 88 | 89 | ## Troubleshooting 90 | 91 | - **File Permission Issues**: If you encounter permission errors, ensure you have write access to the target directory 92 | - **Existing Files**: The installer will safely back up existing files, but check the backup directory if you need to recover previous versions 93 | 94 | For more information about using the Handoff Manager itself, refer to the documentation in `handoffs/0-instructions/` after installation. -------------------------------------------------------------------------------- /handoff-system/0-instructions/prompts/RS-restore-session.md: -------------------------------------------------------------------------------- 1 | # Session Restoration Guide 2 | 3 | Use this prompt when returning to a project after breaks or context resets to efficiently restore project context. 4 | 5 | ## Workflow-Guided Prompt 6 | 7 | ``` 8 | I need to restore context for this project. Please follow the session restoration workflow. 9 | ``` 10 | 11 | ## Standard Prompt Template 12 | 13 | ``` 14 | I need to restore context for this project. Please: 15 | 16 | 1. Follow the session restoration workflow to: 17 | - Scan the project directory for handoffs 18 | - Check if handoffs exist in the root directory 19 | - Read milestone summaries in sequential order 20 | - Read handoff documents if they exist 21 | - Process conversation extracts if available 22 | - Summarize the current project state 23 | ``` 24 | 25 | ## Enhanced Restoration Workflow 26 | 27 | ``` 28 | Before we begin, please: 29 | 30 | 1. Examine the handoffs/ directory structure 31 | 2. Check if handoff documents exist in the root directory 32 | 33 | If handoff documents exist in the root directory: 34 | 35 | A. First review all milestone directories in numerical order 36 | - Read ONLY the 0-prefixed documents in each milestone directory 37 | - Skip any numbered documents within milestone directories 38 | 39 | B. Then read ALL handoff documents in the root directory in numerical order 40 | - Pay special attention to the most recent handoff for current state 41 | 42 | If NO handoff documents exist in the root directory: 43 | 44 | - Review all milestone directories in numerical order 45 | - Read ONLY the 0-prefixed documents in each milestone directory 46 | - Skip any numbered documents within milestone directories 47 | 48 | After reading, please verify your understanding by: 49 | 1. Listing all milestone directories in numerical order 50 | 2. Listing all handoff documents you've read (if any) 51 | 3. Summarizing the current project state and next steps 52 | ``` 53 | 54 | ## Project-Specific Customization 55 | 56 | Add additional project-specific files to read: 57 | 58 | ``` 59 | Additionally, please read these key project files: 60 | - README.md for project overview 61 | - .clinerules for workspace specific guidance 62 | - [specific file paths relevant to your current work] 63 | - [configuration files needed for context] 64 | ``` 65 | 66 | ## Advanced Verification 67 | 68 | For more comprehensive verification: 69 | 70 | ``` 71 | Please verify your understanding more deeply by: 72 | 1. Listing major features completed across all milestones 73 | 2. Identifying recurring patterns or lessons from milestone documents 74 | 3. Summarizing the most important open issues from handoff documents 75 | 4. Explaining the overall project architecture as you understand it 76 | ``` 77 | 78 | ## Session Focus 79 | 80 | To guide the session toward specific goals: 81 | 82 | ``` 83 | After restoring context, please focus on: 84 | - [specific feature or component to work on] 85 | - [particular problem that needs solving] 86 | - [next steps in the project roadmap] 87 | ``` 88 | 89 | ## Conversation Extract Integration 90 | 91 | To incorporate conversation extract insights: 92 | 93 | ``` 94 | I need to restore context for this project with conversation history insights. Please: 95 | 96 | 1. Follow the session restoration workflow 97 | 2. After reading handoffs and milestones, also review the extracted_conversation.md file 98 | 3. Incorporate insights from the conversation history into your understanding 99 | 4. Identify any recent decisions or discoveries from the conversation that might affect current work 100 | ``` 101 | 102 | ## Context Loading Optimization 103 | 104 | For efficient token usage, the handoff-manager prioritizes information as follows: 105 | 106 | | Context Type | Loading Strategy | 107 | |--------------|------------------| 108 | | Older Milestones | Summary documents only | 109 | | Recent Milestones | Full details from summary docs | 110 | | Handoffs in Root | All details (complete read) | 111 | | Latest Handoff | Maximum attention (primary context) | 112 | | Conversation Extract | Process if available (optional) | -------------------------------------------------------------------------------- /handoff-system/0-instructions/0-intro.md: -------------------------------------------------------------------------------- 1 | # Handoff Manager System 2 | 3 | ## Core Concept 4 | 5 | The Handoff Manager provides structured workflows for maintaining optimal context between LLM sessions through: 6 | 7 | 1. **Handoffs**: Sequential session reports capturing completed work 8 | 2. **Milestones**: Consolidated knowledge from multiple handoffs 9 | 3. **Conversation Extraction**: Optional analysis of conversation history 10 | 11 | ```mermaid 12 | graph TD 13 | H[Handoff Documents] -->|"Consolidate 3-5"| M[Milestone Documents] 14 | M -->|"Provide reference for"| N[New Project Phase] 15 | N -->|"Generate new"| H 16 | 17 | C[Conversation Extract] -.->|"Optional
Enhancement"| H 18 | ``` 19 | 20 | ## Workflow-Guided Process 21 | 22 | The Handoff Manager follows clear workflow diagrams for each operation: 23 | 24 | 1. **Creation Workflow**: Guides handoff and milestone creation decisions 25 | 2. **Restoration Workflow**: Optimizes context loading from existing documents 26 | 27 | ## Documents Structure 28 | 29 | **Handoffs**: 30 | - Numbered sequentially (1-setup.md, 2-implementation.md) 31 | - Located in handoffs/ root directory 32 | - Contain specific completed work details 33 | - Enhanced with conversation extracts when available 34 | 35 | **Milestones**: 36 | - Stored in numbered folders (1-feature-complete/) 37 | - Consolidate multiple handoff documents 38 | - Summarize achievements and lessons learned 39 | 40 | ## Creation Triggers 41 | 42 | **Create handoff documents when**: 43 | - Completing a significant project segment 44 | - Context becomes ~30% irrelevant to current task 45 | - After 10+ conversation exchanges 46 | - During debugging sessions exceeding 5 exchanges without resolution 47 | 48 | **Create milestone documents when**: 49 | - Major feature/component implementation complete 50 | - Project phase completed 51 | - 3-5 handoffs accumulated since last milestone 52 | - Critical problem solved with valuable lessons 53 | - Project reaches stable/deployable state 54 | 55 | ## Context Assessment Process 56 | 57 | Before each major response: 58 | 1. Review context window contents: 59 | - Most relevant: current task, recent files, active discussions 60 | - Moderately relevant: background information, earlier work 61 | - Low relevance: initial setup, tangential discussions 62 | 2. Determine if handoff needed based on assessment 63 | 64 | ## Implementation 65 | 66 | To implement the Handoff Manager system: 67 | 68 | 1. Install the system files in your project: 69 | - Copy `.roomodes` file to project root 70 | - Copy `.clinerules` file to project root 71 | - Create handoffs/ directory structure 72 | 73 | 2. Use the handoff-manager mode for all operations: 74 | ``` 75 | I need to create a handoff document for our current work. Please follow the handoff creation workflow. 76 | ``` 77 | 78 | 3. Optional: Use conversation extraction to enhance handoffs 79 | ``` 80 | python handoffs/chat_history/extract_conversation.py conversation.md extracted_conversation.md 81 | ``` 82 | 83 | ## Compatibility 84 | 85 | - Optimized for all Claude 3 models 86 | - Works with all Anthropic models supporting Markdown and Mermaid diagrams 87 | 88 | ## Process Flow 89 | 90 | ```mermaid 91 | graph TD 92 | Start[Begin Project] --> HD1[Create Handoff Document] 93 | HD1 --> Continue{Continue Work?} 94 | Continue -->|Yes| HD2[Create Next Handoff] 95 | HD2 --> Accumulate{3-5 Handoffs
Accumulated?} 96 | Accumulate -->|No| Continue 97 | Accumulate -->|Yes| Milestone[Create Milestone] 98 | Milestone --> NewPhase[New Project Phase] 99 | NewPhase --> Continue 100 | Continue -->|No| End[Project Complete] 101 | 102 | subgraph "Fresh LLM Session" 103 | HD1 104 | HD2 105 | Milestone 106 | end 107 | ``` 108 | 109 | ## Reference Documentation 110 | 111 | - [1-handoff-instructions.md](./1-handoff-instructions.md): Handoff document format 112 | - [2-milestone-instructions.md](./2-milestone-instructions.md): Milestone process 113 | - [3-milestone-scripts.md](./3-milestone-scripts.md): Automation scripts 114 | - [Prompts](./prompts/): Templates for common operations --------------------------------------------------------------------------------