feat(autoskills): markdown scanner + LLM-driven mode (--from-spec, --scan-docs, subcommands)#104
Open
krlosflipdev wants to merge 18 commits into
Open
feat(autoskills): markdown scanner + LLM-driven mode (--from-spec, --scan-docs, subcommands)#104krlosflipdev wants to merge 18 commits into
--from-spec, --scan-docs, subcommands)#104krlosflipdev wants to merge 18 commits into
Conversation
- widen Technology interface with optional aliases?: string[] and description?: string - add tests/fixtures/specs/: well-formed, only-fences, only-heading, empty, malformed, non-english - add tests/fixtures/projects/: with-claude-md, with-agents-md, with-both (package.json + CLAUDE.md/AGENTS.md) - no existing SKILLS_MAP entries changed; 332 existing tests still pass; tsc clean
…lpers - add scanMarkdown(content, skillsMap) -> MarkdownMatch[] with JSON fence branch (deps + devDeps) - extract fences, skip malformed JSON, skip no-language fences, dedupe by techId - add test helpers: writeMarkdown, readFixtureSpec, parseJsonOutput, buildMarkdownFromParts, mockInstaller - parseJsonOutput uses backward line-walk for nested JSON and top-level arrays - unicode-safe evidence truncation in scanner - 344 tests pass, tsc clean
…alias matching - shell fences (bash/sh/shell/zsh): extract from npm/pnpm/yarn/bun add/install with \b anchor + shell-operator chain stop - yaml/toml fences: match against detect.configFileContent patterns - ruby/gemfile fences: match `gem '<name>'` against detect.gems - stack headings (h1-h3, EN + Tecnologias): parse bullets, normalize, match via name + aliases - seed aliases on nextjs, vue, svelte, tailwind, typescript, node - 363 tests pass, tsc clean
- add loadMarkdownSources({fromSpec,scanDocs,projectDir}) to lib.ts: reads --from-spec, auto-discovers CLAUDE.md/AGENTS.md, dedupes by absolute path, throws "spec file not found" on missing fromSpec
- add mergeMarkdownDetections(coreIds,matches): union preserving core order then scanner order
- scanner: 5 edge-case tests (precedence, empty, 100KB, unterminated fence, cross-fence dedup); no scanner logic changes
- 382 tests pass, tsc clean
- main.ts: parse --from-spec <path> and --scan-docs; gate loadMarkdownSources+scanMarkdown+mergeMarkdownDetections behind opt-in; shadow detected/combos/isFrontend defaulting to core.*; parseArgs validates --from-spec arg - add cli-json.ts: serializeList/DryRun/Install/Error; ListJson hides detect; aliases defensively copied - REGRESSION guard: default autoskills ignores CLAUDE.md - 400 tests pass, tsc clean
- subcommands.ts: runList (json + human + alias filter) and runPrompt (reads shipped prompts/skill-selection.md) - resolvePromptPath tries dev + dist layouts (source: pkg/prompts, built: pkg/dist/../prompts) - promptPath DI for testability + ENOENT try/catch -> prompt-file-missing JSON envelope - ship prompts/skill-selection.md (LLM selection guide, v1) - package.json files: add "prompts"; version unchanged (owner releases) - 409 tests pass, tsc clean
- runInstall: parse comma-separated ids, dedupe, validate against SKILLS_MAP - Levenshtein <=2 fuzzy suggestions (catalog-order tiebreak) for unknown ids - install-missing-only / install-empty-only / install-unknown-id JSON envelopes - parallel installSkill via Promise.all with mockInstaller DI hook for tests - human + json output modes; exit 1 on any failure or validation error - autoYes reserved for T17 interactive prompt - 420 tests pass, tsc clean
…low; --dry-run --json emits serializeDryRun; banner/printDetected gated on !args.json - parseArgs: positional subcommand + --only/--filter/--json/--path; consumed-index tracking; implicit --filter for `list <id>` - ArgError class -> structured cli-arg-invalid / internal-error envelopes on --json - --json without subcommand or --dry-run rejected with envelope - unknown-subcommand envelope - installer: AUTOSKILLS_MOCK_INSTALL @internal test hook - 448 tests pass, tsc clean, REGRESSION intact
- packages/autoskills/README.md: Options table (+--from-spec, --scan-docs, --json), new sections Markdown scanner (opt-in) + Subcommands (for LLM integration); fix -a syntax example; complete error codes list - root README.md: Options block +new flags, new LLM-driven mode section linking package README - AGENTS.md: fix stale .mjs refs -> .ts; expand shared helpers list with writeMarkdown/readFixtureSpec/parseJsonOutput/buildMarkdownFromParts/mockInstaller
- normalizeHeadingTitle: strip numbering, emoji, bold/italic, brackets, colon, trailing paren - extractStackBlocks: isStackHeading(line) via normalize-then-compare - accept numbered bullets (1./1)), comma-separated inline, GFM tables - table cell normalization: links, images, bold/italic, backticks, emoji; multi-tech split on comma - pickTechColumn heuristic (tech/framework/library/package/dependency/name/stack) + fallback col 1 - MarkdownMatch API unchanged: all new detections reuse source: "stack-heading" - 32 new tests (14 helper + 7 heading decoration + 2 numbered + 3 inline + 6 tables); 480/480 pass
- loadMarkdownSources: add README.md alongside CLAUDE.md / AGENTS.md (order preserved) - warning text updated: "no CLAUDE.md, AGENTS.md, or README.md found" - tests: new README.md-only and three-file cases in load-md-sources - cli-from-spec: update warning assertion to match new string
- STACK_KEYWORDS: remove "tecnologías" / "tecnologias" — keep keyword set language-agnostic; accepted headings self-evident from listed English keywords - tests: update heading-keywords test title + array; delete orphan fixture tests/fixtures/specs/non-english.md (no test imported it) - packages/autoskills/README.md: rewrite "Bullet format" → "Supported formats under stack headings" with heading-shape examples, 4 content formats (dash/numbered bullets, GFM tables with header heuristic, comma-inline), normalization rules - packages/autoskills/README.md: document --from-spec extension flexibility (.md/.mdx/.markdown/.txt); note "Also:" prefixes not stripped; heuristic keyword list includes plurals; stack-headings bullet points to new subsection - root README.md: sync Options + expand blockquote (fences, keywords, content formats, decorated headings, tables-outside-heading exclusion)
- clipboard.ts: cross-platform copy via spawn (pbcopy/wl-copy→xclip/clip.exe), zero deps; ENOENT/exit/error all distinguished - subcommands.ts: runCopyPrompt reuses resolvePromptPath; success → ✓ msg + Cmd/Ctrl+V hint; failure → prompt to stdout + warning to stderr (exit 0) - main.ts: --copy-prompt early-exit before subcommand dispatch (mirrors --help) - prompts/skill-selection.md → spec-generator-prompt.md: LLM now generates docs/specs-initial.md from user requirement (heading + dash bullets), instructs user to run --from-spec themselves (no install) - 13 new tests (8 clipboard + 5 copy-prompt); 497/497 pass
BREAKING: `autoskills prompt` and `--copy-prompt` removed.
Use `--show-specgen-prompt` or `--copy-specgen-prompt` instead.
- new clipboard.ts: cross-platform spawn copy (pbcopy/wl-copy→xclip/clip.exe), zero deps; ENOENT/exit/error distinguished, fallback prints content + warning
- new --show-specgen-prompt + --copy-specgen-prompt: top-level flags, early-exit before dispatch (mirrors --help); show wins if both passed
- drop prompt subcommand + --path flag; KNOWN now {list, install}
- READMEs: document spec-doc flow with two chat variants (bash-tool first, paste second); root example reframed as problem statement
- tests: +13, -3; 495/495 pas
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What Changed
Adds an opt-in markdown scanner and an LLM-driven workflow to
autoskills, alongside machine-readable JSON output and new subcommands for agent integration.New CLI flags
--from-spec <path>: parse a spec file (.md/.mdx/.markdown/.txt) and install detected skills.--scan-docs: auto-scanCLAUDE.md/AGENTS.md/README.mdat project root.--json: structured output for every mode (list / dry-run / install) with typed error envelopes.--show-specgen-prompt/--copy-specgen-prompt: print / copy the spec-generator prompt to stdin/clipboard for LLM use.New subcommands
autoskills list [id] [--filter <alias>] [--json]: list catalog or inspect one skill (alias-aware).autoskills install --only <ids> [-y] [--json]: install comma-separated ids with fuzzy suggestion (Levenshtein ≤ 2) and parallelinstallSkillexecution.Markdown scanner (
markdown-scanner.ts, 332 lines)json(deps/devDeps),bash/sh/shell/zsh(npm/pnpm/yarn/bun add/install),yaml/toml(configFileContent patterns),ruby/gemfile(gem '<name>').1./1)), comma-separated inline, GFM tables with heuristic tech-column picker (tech/framework/library/package/dependency/name/stack→ fallback col 1).Technology.aliases?: string[]; seeded onnextjs,vue,svelte,tailwind,typescript,node.Clipboard (
clipboard.ts, 84 lines)spawn:pbcopy(macOS),wl-copy→xclip(Linux),clip.exe(Windows/WSL).ENOENT/ exit-code / error states.Spec-generator prompt
prompts/spec-generator-prompt.md: LLM generatesdocs/specs-initial.mdfrom user requirement; instructs user to run--from-specthemselves (no install).JSON envelopes (
cli-json.ts, 104 lines)serializeList/serializeDryRun/serializeInstall/serializeError.cli-arg-invalid,spec-file-missing,install-missing-only,install-empty-only,install-unknown-id,prompt-file-missing,unknown-subcommand,internal-error.Breaking change
autoskills promptsubcommand and--copy-promptflag removed. Use--show-specgen-prompt/--copy-specgen-promptinstead.Why This Change
Existing
autoskillsonly detected tech viapackage.json/ lockfiles / framework config files. This misses projects where the stack is declared in docs (CLAUDE.md,AGENTS.md,README.md, spec files) before code exists — the common greenfield / LLM-assisted workflow.Goals:
--json) + a structured prompt (--copy-specgen-prompt) so Claude/Codex/other agents can drive skill selection end-to-end.--from-spec/--scan-docs). Defaultautoskillsstill ignores markdown.Testing Done
Test additions:
markdown-scanner.test.ts(341 lines): JSON / shell / yaml / toml / ruby fences, stack headings (bullets / numbered / inline / tables), heading decorations, alias matching, unicode-safe truncation, edge cases (empty, unterminated fence, 100 KB, cross-fence dedup).cli-from-spec.test.ts,cli-json.test.ts,dry-run-json.test.ts,errors.test.ts,install-only.test.ts,load-md-sources.test.ts,merge-md.test.ts,subcommands.test.ts,subcommands-list-prompt.test.ts,clipboard.test.ts,copy-prompt.test.ts,helpers.test.ts,logging.test.ts.tests/fixtures/specs/(well-formed, only-fences, only-heading, empty, malformed) +tests/fixtures/projects/(with-claude-md, with-agents-md, with-both).Verification commands:
Backwards compat: core test suite unchanged (332 pre-existing tests still pass); REGRESSION guard ensures default run ignores
CLAUDE.md.Type of Change
fix:Bug fixfeat:New featurerefactor:Code refactoringdocs:Documentationtest:Testschore:Maintenance/toolingContains one BREAKING commit (
7452cc7):--copy-prompt/promptsubcommand renamed.Security & Quality Checklist
Notes:
clipboard.tsusesspawnwith argv arrays (no shell string interpolation) — no command-injection surface.eval/ dynamicimport/ shell exec of parsed content.--from-specthrowsspec-file-missingon non-existent paths; no silent read from unexpected locations.Documentation
Doc changes:
README.md(root): Options block extended with new flags; added LLM-driven mode section linking package README.packages/autoskills/README.md: full Options table; new sections Markdown scanner (opt-in) + Subcommands (for LLM integration); supported heading formats (4 content formats: dash/numbered bullets, GFM tables, comma-inline); normalization rules;--from-specextension flexibility; complete error codes list.AGENTS.md: fixed stale.mjsreferences to.ts; expanded shared helpers list.Commits (16 feature + 1 merge)
Diff summary
New files:
markdown-scanner.ts,cli-json.ts,clipboard.ts,subcommands.ts,prompts/spec-generator-prompt.md, 13 new test files, 10 fixture files.