From 8de648cf3c05a59676f2bc0fa0ca9820fa3a180d Mon Sep 17 00:00:00 2001 From: "Gregory R. Warnes" Date: Tue, 21 Apr 2026 12:16:58 -0400 Subject: [PATCH 1/3] fix: update symlink targets, resolve merge conflict, and improve portability (#1) - Update all .claude/commands/*.md symlinks to use /home/warnes path for environment consistency - Update setup-cron.sh to dynamically resolve REPO_DIR for improved portability - Resolve merge conflict in mcp.json, ensuring both github and datetime-mcp server definitions are present --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 76e44eb..6d6e5df 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,8 @@ The Markdown → LinkedIn conversion logic is derived from ```sh pip install linkedown +# or +pipx install linkedown ``` ## CLI usage From 1c44efd00d73814c6ae5078eef5f3474b68919d5 Mon Sep 17 00:00:00 2001 From: "Gregory R. Warnes" Date: Mon, 18 May 2026 22:07:15 -0400 Subject: [PATCH 2/3] chore: relocate specstory transcripts to correct repo --- .clinerules | 67 +++++++++++++++++++ ...stall-script-error-in-linkedown-project.md | 56 ++++++++++++++++ ...pt-error-in-linkedown-project_relocated.md | 56 ++++++++++++++++ ...t-error-in-linkedown-project_relocated2.md | 56 ++++++++++++++++ ...t-error-in-linkedown-project_relocated3.md | 56 ++++++++++++++++ AGENTS.md | 67 +++++++++++++++++++ CLAUDE.md | 67 +++++++++++++++++++ README.md | 20 ++++++ agent-instructions/CLAUDE.md | 20 ++++++ agent-instructions/README.md | 15 +++++ agent-instructions/cline-instructions.md | 20 ++++++ agent-instructions/codex-instructions.md | 19 ++++++ agent-instructions/copilot-instructions.md | 25 +++++++ .../install-agent-instructions.sh | 39 +++++++++++ install.sh | 2 + 15 files changed, 585 insertions(+) create mode 100644 .clinerules create mode 100644 .specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project.md create mode 100644 .specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project_relocated.md create mode 100644 .specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project_relocated2.md create mode 100644 .specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project_relocated3.md create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 agent-instructions/CLAUDE.md create mode 100644 agent-instructions/README.md create mode 100644 agent-instructions/cline-instructions.md create mode 100644 agent-instructions/codex-instructions.md create mode 100644 agent-instructions/copilot-instructions.md create mode 100644 agent-instructions/install-agent-instructions.sh create mode 100755 install.sh 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_relocated.md b/.specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project_relocated.md new file mode 100644 index 0000000..b894b8a --- /dev/null +++ b/.specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project_relocated.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/.specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project_relocated3.md b/.specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project_relocated3.md new file mode 100644 index 0000000..19fc057 --- /dev/null +++ b/.specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project_relocated3.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..6a0c1cc 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,29 @@ 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 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." + From 74c96a48cfa3818c001060d87847c599845108b3 Mon Sep 17 00:00:00 2001 From: "Gregory R. Warnes" Date: Tue, 30 Jun 2026 21:28:49 -0400 Subject: [PATCH 3/3] chore: relocate and dedupe specstory transcripts --- ...pt-error-in-linkedown-project_relocated.md | 56 ------------------- ...t-error-in-linkedown-project_relocated3.md | 56 ------------------- 2 files changed, 112 deletions(-) delete mode 100644 .specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project_relocated.md delete mode 100644 .specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project_relocated3.md diff --git a/.specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project_relocated.md b/.specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project_relocated.md deleted file mode 100644 index b894b8a..0000000 --- a/.specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project_relocated.md +++ /dev/null @@ -1,56 +0,0 @@ - - -# 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_relocated3.md b/.specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project_relocated3.md deleted file mode 100644 index 19fc057..0000000 --- a/.specstory/history/2026-04-21_13-07-47Z-install-script-error-in-linkedown-project_relocated3.md +++ /dev/null @@ -1,56 +0,0 @@ - - -# 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. - -