diff --git a/.clinerules b/.clinerules new file mode 100644 index 0000000..51ba1f7 --- /dev/null +++ b/.clinerules @@ -0,0 +1,67 @@ + + + +# OBO Session Guidelines + +Use the OBO MCP tools for all One-By-One review session work in this repository. + +## When To Use OBO + +- Use OBO when the user asks to process findings, tasks, or decisions one at a time. +- Use OBO when multiple review findings need explicit sequential approval instead of a flat summary. +- Use OBO when the item list should be resumable and persisted outside the current chat transcript. +- Use OBO when the work may need reordering, blocker tracking, or nested child sessions. +- Prefer normal chat for small single-step tasks that do not need queue state. + +## Required Workflow + +- Never directly create, edit, repair, or reorder files in `.github/obo_sessions/`. +- Use `obo_list_sessions` before starting a new OBO session. +- If an incomplete session exists, use the agent's structured question UI/tool when available to ask whether to resume, merge, replace, or stop. +- Use `obo_create` to start a new session. `items` is optional; if items are not yet known, omit them and add them later with `obo_merge_items`. +- Use `obo_merge_items` to append new findings to an existing session. +- Start the session with an overview of scope, major dependencies, and proposed order. +- Use `obo_next` to fetch the next actionable item. +- Use `obo_mark_in_progress` when beginning work on an item. +- Use `obo_mark_blocked` when an item cannot proceed and the blocker should be stored. +- Use `obo_create_child_session` when a nested sub-session is needed. +- Use `obo_complete_child_session` to finish the child and resume the parent. +- Use `obo_set_approval` to record approval decisions, timing, and delayed-review transitions. +- Use `obo_mark_complete` or `obo_mark_skip` to resolve an item. +- Use `obo_session_status` or `obo_list_items` instead of reading `index.json` directly. +- Use `obo_complete_session` when all actionable items are resolved. +- Use the agent's structured question UI/tool for predefined OBO choices such as resume, merge, replace, approval, navigation, stop, restore, and reorder instead of plain-text numbered menus. +- Only fall back to plain text when no structured question tool exists, the tool is failing, or the response truly must be open-ended; state that reason explicitly before falling back. + +## Session Conventions + +- Session files live in `.github/obo_sessions/`. +- New session filenames must follow `session_YYYYMMDD_HHMMSS.json`. +- Item lifecycle states include `pending`, `in_progress`, `deferred`, `blocked`, `completed`, and `skipped`. +- Item approval states include `unreviewed`, `approved`, and `denied`; approval timing is stored in `approval_mode` as `immediate`, `delayed`, or `null`. +- Parent sessions may be `paused` while a child session is active. +- Treat the MCP server as the source of truth for session state. + +## Review Behavior + +- For multiple findings, keep the OBO session updated after every user-approved action. +- For a single finding, still use the MCP session flow if the user asks for OBO handling. +- If a needed operation is not available through the MCP tools, tell the user instead of editing session JSON manually. + +## Release Workflow + +- Treat testing, tagging, releasing, and publishing as a staged workflow: inspect repo state, run tests, complete release-prep edits, validate packaging, then handle remote release steps. +- Prefer the verified release test command `.venv/bin/python -m pytest tests/test_session.py tests/test_server.py` unless the user explicitly requests a different scope. +- Keep release edits minimal and targeted. Do not revert unrelated dirty-worktree files unless the user explicitly asks. +- Before any irreversible action, pause for confirmation even if the user's initial request already said to publish. +- The required confirmation boundary includes each of these actions: `git push`, tag creation, GitHub release creation, and PyPI publication. +- When asking for confirmation, summarize the exact action, the version, and the branch or tag involved. +- After a live publish, verify the result end to end: release workflow status, PyPI visibility, and at least one package resolution or install check. +- If clarification, triage, or blocker handling is needed during release work, prefer creating or resuming an OBO session instead of handling it as an unstructured side conversation. + diff --git a/.specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project.md b/.specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project.md new file mode 100644 index 0000000..fb17878 --- /dev/null +++ b/.specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project.md @@ -0,0 +1,56 @@ + + +# 2026-04-21 13:08:13Z + + + +_**User (2026-04-21 13:08:13Z)**_ + +Issues with the install script in `linkedown`: +``` +(oboe-mcp) ➜ linkedown git:(main) ✗ ./install.sh +cp: /Users/warnes/src/linkedown/agent-instructions/copilot-instructions.md: No such file or directory +(oboe-mcp) ➜ linkedown git:(main) ✗ +``` + +--- + +_**Agent (copilot/gpt-4.1)**_ + +MANDATORY PRE-FLIGHT: +This task involves troubleshooting a shell install script in the linkedown repo. The following instructions and skills apply: + +- From linkedown/AGENTS.md: OBO session guidelines, but not directly relevant to install script fixes. +- From user memory: Shell patterns (write temp files to project tmp/), but not directly relevant unless script is modified. +- No direct project-specific install script skill, but general shell scripting and error handling best practices apply. + +Relevant skills: +- code-review (for reviewing/fixing the script) +- workflow-orchestration (for planning the fix) +- agent-customization (if the script is meant to copy agent instructions) + +First, I will inspect the contents of linkedown/install.sh and the agent-instructions/ directory + +--- + +_**User (2026-04-21 13:25:50Z)**_ + +Create agent instructions for the four supported agents following the pattern set in `oboe-mcp/`. + +_**User (2026-04-21 13:33:33Z)**_ + +You misunderstood. You should create files that provide agent instructions on how to use the linkedown project, not the oboe-mcp project. + +_**User (2026-04-21 13:57:57Z)**_ + +Please evaluate the linkedown agent instructions for clarify and completeness. + +_**User (2026-04-21 13:59:54Z)**_ + +Should we move the `install.sh` file into `agent-instructions` and/or rename it (perhaps `install-agent-instructions.sh` to clarify what it does? + +_**User (2026-04-21 14:00:11Z)**_ + +Yes. + + diff --git a/.specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project_relocated2.md b/.specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project_relocated2.md new file mode 100644 index 0000000..467e863 --- /dev/null +++ b/.specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project_relocated2.md @@ -0,0 +1,56 @@ + + +# 2026-04-21 13:08:13Z + + + +_**User (2026-04-21 13:08:13Z)**_ + +Issues with the install script in `linkedown`: +``` +(oboe-mcp) ➜ linkedown git:(main) ✗ ./install.sh +cp: /Users/warnes/src/linkedown/agent-instructions/copilot-instructions.md: No such file or directory +(oboe-mcp) ➜ linkedown git:(main) ✗ +``` + +--- + +_**Agent (copilot/gpt-4.1)**_ + +MANDATORY PRE-FLIGHT: +This task involves troubleshooting a shell install script in the linkedown repo. The following instructions and skills apply: + +- From linkedown/AGENTS.md: OBO session guidelines, but not directly relevant to install script fixes. +- From user memory: Shell patterns (write temp files to project tmp/), but not directly relevant unless script is modified. +- No direct project-specific install script skill, but general shell scripting and error handling best practices apply. + +Relevant skills: +- code-review (for reviewing/fixing the script) +- workflow-orchestration (for planning the fix) +- agent-customization (if the script is meant to copy agent instructions) + +First, I will inspect the contents of linkedown/install.sh and the agent-instructions/ directory + +--- + +_**User (2026-04-21 13:25:50Z)**_ + +Create agent instructions for the four supported agents following the pattern set in `oboe-mcp/`. + +_**User (2026-04-21 13:33:33Z)**_ + +You misunderstood. You should create files that provide agent instructions on how to use the linkedown project, not the oboe-mcp project. + +_**User (2026-04-21 13:57:57Z)**_ + +Please evaluate the linkedown agent instructions for clarify and completeness. + +_**User (2026-04-21 13:59:54Z)**_ + +Should we move the `install.sh` file into `agent-instructions` and/or rename it (perhaps `install-agent-instructions.sh` to clarify what it does? + +_**User (2026-04-21 14:00:11Z)**_ + +Yes. + + diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..51ba1f7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,67 @@ + + + +# OBO Session Guidelines + +Use the OBO MCP tools for all One-By-One review session work in this repository. + +## When To Use OBO + +- Use OBO when the user asks to process findings, tasks, or decisions one at a time. +- Use OBO when multiple review findings need explicit sequential approval instead of a flat summary. +- Use OBO when the item list should be resumable and persisted outside the current chat transcript. +- Use OBO when the work may need reordering, blocker tracking, or nested child sessions. +- Prefer normal chat for small single-step tasks that do not need queue state. + +## Required Workflow + +- Never directly create, edit, repair, or reorder files in `.github/obo_sessions/`. +- Use `obo_list_sessions` before starting a new OBO session. +- If an incomplete session exists, use the agent's structured question UI/tool when available to ask whether to resume, merge, replace, or stop. +- Use `obo_create` to start a new session. `items` is optional; if items are not yet known, omit them and add them later with `obo_merge_items`. +- Use `obo_merge_items` to append new findings to an existing session. +- Start the session with an overview of scope, major dependencies, and proposed order. +- Use `obo_next` to fetch the next actionable item. +- Use `obo_mark_in_progress` when beginning work on an item. +- Use `obo_mark_blocked` when an item cannot proceed and the blocker should be stored. +- Use `obo_create_child_session` when a nested sub-session is needed. +- Use `obo_complete_child_session` to finish the child and resume the parent. +- Use `obo_set_approval` to record approval decisions, timing, and delayed-review transitions. +- Use `obo_mark_complete` or `obo_mark_skip` to resolve an item. +- Use `obo_session_status` or `obo_list_items` instead of reading `index.json` directly. +- Use `obo_complete_session` when all actionable items are resolved. +- Use the agent's structured question UI/tool for predefined OBO choices such as resume, merge, replace, approval, navigation, stop, restore, and reorder instead of plain-text numbered menus. +- Only fall back to plain text when no structured question tool exists, the tool is failing, or the response truly must be open-ended; state that reason explicitly before falling back. + +## Session Conventions + +- Session files live in `.github/obo_sessions/`. +- New session filenames must follow `session_YYYYMMDD_HHMMSS.json`. +- Item lifecycle states include `pending`, `in_progress`, `deferred`, `blocked`, `completed`, and `skipped`. +- Item approval states include `unreviewed`, `approved`, and `denied`; approval timing is stored in `approval_mode` as `immediate`, `delayed`, or `null`. +- Parent sessions may be `paused` while a child session is active. +- Treat the MCP server as the source of truth for session state. + +## Review Behavior + +- For multiple findings, keep the OBO session updated after every user-approved action. +- For a single finding, still use the MCP session flow if the user asks for OBO handling. +- If a needed operation is not available through the MCP tools, tell the user instead of editing session JSON manually. + +## Release Workflow + +- Treat testing, tagging, releasing, and publishing as a staged workflow: inspect repo state, run tests, complete release-prep edits, validate packaging, then handle remote release steps. +- Prefer the verified release test command `.venv/bin/python -m pytest tests/test_session.py tests/test_server.py` unless the user explicitly requests a different scope. +- Keep release edits minimal and targeted. Do not revert unrelated dirty-worktree files unless the user explicitly asks. +- Before any irreversible action, pause for confirmation even if the user's initial request already said to publish. +- The required confirmation boundary includes each of these actions: `git push`, tag creation, GitHub release creation, and PyPI publication. +- When asking for confirmation, summarize the exact action, the version, and the branch or tag involved. +- After a live publish, verify the result end to end: release workflow status, PyPI visibility, and at least one package resolution or install check. +- If clarification, triage, or blocker handling is needed during release work, prefer creating or resuming an OBO session instead of handling it as an unstructured side conversation. + diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..51ba1f7 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,67 @@ + + + +# OBO Session Guidelines + +Use the OBO MCP tools for all One-By-One review session work in this repository. + +## When To Use OBO + +- Use OBO when the user asks to process findings, tasks, or decisions one at a time. +- Use OBO when multiple review findings need explicit sequential approval instead of a flat summary. +- Use OBO when the item list should be resumable and persisted outside the current chat transcript. +- Use OBO when the work may need reordering, blocker tracking, or nested child sessions. +- Prefer normal chat for small single-step tasks that do not need queue state. + +## Required Workflow + +- Never directly create, edit, repair, or reorder files in `.github/obo_sessions/`. +- Use `obo_list_sessions` before starting a new OBO session. +- If an incomplete session exists, use the agent's structured question UI/tool when available to ask whether to resume, merge, replace, or stop. +- Use `obo_create` to start a new session. `items` is optional; if items are not yet known, omit them and add them later with `obo_merge_items`. +- Use `obo_merge_items` to append new findings to an existing session. +- Start the session with an overview of scope, major dependencies, and proposed order. +- Use `obo_next` to fetch the next actionable item. +- Use `obo_mark_in_progress` when beginning work on an item. +- Use `obo_mark_blocked` when an item cannot proceed and the blocker should be stored. +- Use `obo_create_child_session` when a nested sub-session is needed. +- Use `obo_complete_child_session` to finish the child and resume the parent. +- Use `obo_set_approval` to record approval decisions, timing, and delayed-review transitions. +- Use `obo_mark_complete` or `obo_mark_skip` to resolve an item. +- Use `obo_session_status` or `obo_list_items` instead of reading `index.json` directly. +- Use `obo_complete_session` when all actionable items are resolved. +- Use the agent's structured question UI/tool for predefined OBO choices such as resume, merge, replace, approval, navigation, stop, restore, and reorder instead of plain-text numbered menus. +- Only fall back to plain text when no structured question tool exists, the tool is failing, or the response truly must be open-ended; state that reason explicitly before falling back. + +## Session Conventions + +- Session files live in `.github/obo_sessions/`. +- New session filenames must follow `session_YYYYMMDD_HHMMSS.json`. +- Item lifecycle states include `pending`, `in_progress`, `deferred`, `blocked`, `completed`, and `skipped`. +- Item approval states include `unreviewed`, `approved`, and `denied`; approval timing is stored in `approval_mode` as `immediate`, `delayed`, or `null`. +- Parent sessions may be `paused` while a child session is active. +- Treat the MCP server as the source of truth for session state. + +## Review Behavior + +- For multiple findings, keep the OBO session updated after every user-approved action. +- For a single finding, still use the MCP session flow if the user asks for OBO handling. +- If a needed operation is not available through the MCP tools, tell the user instead of editing session JSON manually. + +## Release Workflow + +- Treat testing, tagging, releasing, and publishing as a staged workflow: inspect repo state, run tests, complete release-prep edits, validate packaging, then handle remote release steps. +- Prefer the verified release test command `.venv/bin/python -m pytest tests/test_session.py tests/test_server.py` unless the user explicitly requests a different scope. +- Keep release edits minimal and targeted. Do not revert unrelated dirty-worktree files unless the user explicitly asks. +- Before any irreversible action, pause for confirmation even if the user's initial request already said to publish. +- The required confirmation boundary includes each of these actions: `git push`, tag creation, GitHub release creation, and PyPI publication. +- When asking for confirmation, summarize the exact action, the version, and the branch or tag involved. +- After a live publish, verify the result end to end: release workflow status, PyPI visibility, and at least one package resolution or install check. +- If clarification, triage, or blocker handling is needed during release work, prefer creating or resuming an OBO session instead of handling it as an unstructured side conversation. + diff --git a/README.md b/README.md index 76e44eb..dedce35 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,35 @@ LinkedIn does not render Markdown, but does display Unicode styled characters co `linkedown` converts between the two formats — both as a CLI tool and as an MCP server for use by coding agents. + The Markdown → LinkedIn conversion logic is derived from [md-to-linkedin](https://github.com/shenning00/md-to-linkedin) by Scott Henning (MIT). +## Agent instructions for Copilot, Claude, Codex, and Cline + +To enable agent-aware workflows, `linkedown` provides example agent instruction files for Copilot, Claude, Codex, and Cline in the `agent-instructions/` directory. + +To install these instructions for your VS Code agents, run: + +```sh +cd agent-instructions +./install-agent-instructions.sh +``` + +This will copy the following files to your VS Code user data directory: +- `copilot-instructions.md` +- `CLAUDE.md` +- `codex-instructions.md` +- `cline-instructions.md` + +You can customize these files as needed for your workflow. See `agent-instructions/README.md` for details. + ## Installation ```sh pip install linkedown +# or +pipx install linkedown ``` ## CLI usage diff --git a/agent-instructions/CLAUDE.md b/agent-instructions/CLAUDE.md new file mode 100644 index 0000000..2ec9a5b --- /dev/null +++ b/agent-instructions/CLAUDE.md @@ -0,0 +1,20 @@ +# Claude Agent Instructions for linkedown + +## Overview +linkedown provides Markdown ↔ LinkedIn Unicode conversion as both a CLI and an MCP server. + +### CLI Usage +- Convert Markdown to LinkedIn Unicode: `md2li input.md [-o output.txt] [--copy]` +- Convert LinkedIn Unicode to Markdown: `li2md input.txt [-o output.md]` + +### MCP Server +- Start with: `linkedown-mcp` +- Exposes tools: `md_to_linkedin_tool`, `linkedin_to_md_tool` + +### Agent Guidance +- Use CLI for file/clipboard conversion. +- Use MCP server for agent-driven conversion tasks. +- Refer to the README for formatting details and examples. + +--- +For installation, see agent-instructions/README.md. diff --git a/agent-instructions/README.md b/agent-instructions/README.md new file mode 100644 index 0000000..2bd22f1 --- /dev/null +++ b/agent-instructions/README.md @@ -0,0 +1,15 @@ +# Agent Instructions for linkedown + +This directory contains example agent instruction files for Copilot, Claude, Codex, and Cline. To install them for your VS Code agents, run: + +```sh +./install-agent-instructions.sh +``` + +This will copy the following files to your VS Code user data directory: +- `copilot-instructions.md` +- `CLAUDE.md` +- `codex-instructions.md` +- `cline-instructions.md` + +You can customize these files as needed for your workflow. diff --git a/agent-instructions/cline-instructions.md b/agent-instructions/cline-instructions.md new file mode 100644 index 0000000..a42b49f --- /dev/null +++ b/agent-instructions/cline-instructions.md @@ -0,0 +1,20 @@ +# Cline Agent Instructions for linkedown + +## linkedown Capabilities +- Converts Markdown ↔ LinkedIn Unicode-styled text +- CLI and MCP server modes + +## Usage +- **CLI:** + - `md2li input.md [-o output.txt] [--copy]` + - `li2md input.txt [-o output.md]` +- **MCP Server:** + - Start: `linkedown-mcp` + - Tools: `md_to_linkedin_tool`, `linkedin_to_md_tool` + +## Agent Workflow +- Use CLI for direct file or clipboard conversion. +- Use MCP server for agent-driven or automated conversion. +- See README for formatting and examples. + +Install instructions: agent-instructions/README.md diff --git a/agent-instructions/codex-instructions.md b/agent-instructions/codex-instructions.md new file mode 100644 index 0000000..8d7bf7e --- /dev/null +++ b/agent-instructions/codex-instructions.md @@ -0,0 +1,19 @@ +# Codex Agent Instructions for linkedown + +## What is linkedown? +A tool for converting Markdown to LinkedIn Unicode-styled text and back. Available as a CLI and MCP server. + +## How to Use +- **CLI:** + - Markdown → LinkedIn: `md2li input.md [-o output.txt] [--copy]` + - LinkedIn → Markdown: `li2md input.txt [-o output.md]` +- **MCP Server:** + - Start: `linkedown-mcp` + - Tools: `md_to_linkedin_tool`, `linkedin_to_md_tool` + +## Agent Integration +- Use CLI for local/manual conversion. +- Use MCP server for automated or agent workflows. +- Formatting rules and examples are in the README. + +See agent-instructions/README.md for install steps. diff --git a/agent-instructions/copilot-instructions.md b/agent-instructions/copilot-instructions.md new file mode 100644 index 0000000..a713955 --- /dev/null +++ b/agent-instructions/copilot-instructions.md @@ -0,0 +1,25 @@ +# Copilot Agent Instructions for linkedown + +## Purpose +linkedown converts between Markdown and LinkedIn Unicode-styled text. Use it to prepare posts for LinkedIn or to recover Markdown from LinkedIn-formatted text. + +## Usage +- **CLI:** + - Markdown → LinkedIn: `md2li input.md [-o output.txt] [--copy]` + - LinkedIn → Markdown: `li2md input.txt [-o output.md]` +- **MCP Server:** + - Start: `linkedown-mcp` + - Tools: `md_to_linkedin_tool`, `linkedin_to_md_tool` + +## Agent Workflow +- Use the CLI for local file or clipboard conversion. +- Use the MCP server for programmatic conversion in agent workflows. +- For supported formatting, see the linkedown README. + +## Example +```sh +md2li post.md --copy +li2md linkedin.txt -o post.md +``` + +See agent-instructions/README.md for install details. diff --git a/agent-instructions/install-agent-instructions.sh b/agent-instructions/install-agent-instructions.sh new file mode 100644 index 0000000..42c67d4 --- /dev/null +++ b/agent-instructions/install-agent-instructions.sh @@ -0,0 +1,39 @@ +#!/bin/bash +# install-agent-instructions.sh — Install agent instructions for Copilot, Claude, Codex, and Cline +# SPDX-FileCopyrightText: 2024 Greg Warnes +# SPDX-License-Identifier: MIT + +set -e + +# Determine script directory +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +# Paths to agent instruction templates (assume they are in agent-instructions/) +INSTRUCTIONS_DIR="$SCRIPT_DIR" + +# VS Code user data dir (macOS default) +VSCODE_USER_DIR="$HOME/Library/Application Support/Code/User" + +# Ensure agent-instructions directory exists +if [ ! -d "$INSTRUCTIONS_DIR" ]; then + echo "Error: agent-instructions/ directory not found in $SCRIPT_DIR." + exit 1 +fi + +# Copy Copilot instructions +cp "$INSTRUCTIONS_DIR/copilot-instructions.md" "$VSCODE_USER_DIR/copilot-instructions.md" +echo "✓ Copilot instructions installed." + +# Copy Claude instructions +cp "$INSTRUCTIONS_DIR/CLAUDE.md" "$VSCODE_USER_DIR/CLAUDE.md" +echo "✓ Claude instructions installed." + +# Copy Codex instructions +cp "$INSTRUCTIONS_DIR/codex-instructions.md" "$VSCODE_USER_DIR/codex-instructions.md" +echo "✓ Codex instructions installed." + +# Copy Cline instructions +cp "$INSTRUCTIONS_DIR/cline-instructions.md" "$VSCODE_USER_DIR/cline-instructions.md" +echo "✓ Cline instructions installed." + +echo "All agent instructions installed." diff --git a/install.sh b/install.sh new file mode 100755 index 0000000..16c2d3c --- /dev/null +++ b/install.sh @@ -0,0 +1,2 @@ +echo "All agent instructions installed." +