Content & Media Creation · lllllllama/rigorpilot-skills

repo-intake-and-plan

Name: repo-intake-and-plan
Author: lllllllama/rigorpilot-skills

Rigor Intake helper for README-first deep learning repo reproduction. Use when the task is specifically to scan a repository, read the README and common project files, extract documented commands, classify inference, evaluation, and training candidates, and return the smallest trustworthy reproduction plan to the main orchestrator. Do not use for environment setup, asset download, command execution, final reporting, paper lookup, or end-to-end orchestration.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandDual-pass Audit

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

The foundation of this skill rests on two deterministic Python scripts: scan_repo.py performs structure/signal scanning, while extract_commands.py extracts and classifies commands from the README; SKILL.md merely defines when to use them and what to output. Command extraction is not a process of 'letting the model read the README and guess', but a reproducible pipeline driven by regular expressions, header attribution, and heuristic classification.

skills/repo-intake-and-plan/scripts/extract_commands.py

"""Extract shell-like commands from README content and classify them."""

The same file defines four classification categories: inference / evaluation / training / other, with three priority sets: SCRIPT_CATEGORY_HINTS, SETUP_PREFIXES, and ASSET_PREFIXES. Turning 'command extraction' into a testable pure function (extract_commands(readme_text, readme_dir)) is the prerequisite for this skill to be repeatedly regressed in CI.

The scanning scope is fixed by a whitelist: it inspects only 9 key files and 7 high-signal directories without traversing the entire repository; results and warnings are directly produced by the script (e.g., explicitly warning if a README is missing) rather than free-form model descriptions.

skills/repo-intake-and-plan/scripts/scan_repo.py

KEY_FILES = [ "README.md", "README", "requirements.txt", "environment.yml", "environment.yaml", "pyproject.toml", "setup.py", "setup.cfg", "Dockerfile", ]

SIGNAL_DIRS covers configs/config/scripts/tools/examples/notebooks/checkpoints; warnings will state 'No README file was found at the repository root.' and 'No common environment or packaging files were detected.'. The output includes readme_path, detected_files, detected_dirs, and top_level counts—all structured fields consumable by an orchestrator (run_json parses stdout).

The classifier implements explicit priorities and reasoning: setup/asset syntax is evaluated first (preventing installation steps from being classified as inference), followed by header semantics, entrypoint script name heuristics (train*.py / eval*.py / sample|generate|infer*.py), and finally keyword scanning as a fallback.

skills/repo-intake-and-plan/scripts/extract_commands.py

# Unambiguous setup/asset syntax outranks generic headings such as # "Basic Example", which otherwise makes installation look like inference. if lowered.startswith(SETUP_PREFIXES + ASSET_PREFIXES): return "other"

The weight of the entrypoint script name heuristic is explicitly documented in the comments: 'The entrypoint script name is the strongest category signal: flags like --eval_iters on a train.py command must not flip training into evaluation (that would bypass the training-authorization gate downstream).'—demonstrating that classification results feed directly into downstream training authorization gates, where misclassification carries real consequences, thereby justifying deliberately conservative rules.

It performs structural inspection on .py entrypoints referenced in the README: reading the script (≤512 KiB) and scoring it based on occurrences of optimizer.step(/backward(/train()/def train*/epoch loops; a score of ≥4 promotes the command's classification to training, recording classification_source='entrypoint-structure' and evidence tags.

skills/repo-intake-and-plan/scripts/extract_commands.py

TRAINING_STRUCTURE_SIGNALS = [ ("optimizer-step", re.compile(r"\boptimizer\s*\.\s*step\s*\(", re.IGNORECASE), 3), ("backward-pass", re.compile(r"\.\s*backward\s*\(", re.IGNORECASE), 3), ("model-train-mode", re.compile(r"\.\s*train\s*\(", re.IGNORECASE), 2), ("train-function", re.compile(r"\bdef\s+train\w*\s*\(", re.IGNORECASE), 1), ("epoch-loop", re.compile(r"\bfor\s+\w*epoch\w*\s+in\b", re.IGNORECASE), 1), ]

Guardrails are enforced prior to reading files: referenced_python_script() validates paths using candidate.relative_to(root), immediately returning None for any path escaping the repository root—preventing traversal outside the repo via ../ in README paths. This represents the only code path in this skill that inspects repository file contents.

'Classification can be conservative enough to admit ignorance' is codified into the reference: when evidence is insufficient, candidates are labeled as inferred, preferring documented ambiguity over over-promising; explicit README evidence takes precedence over filename heuristics.

skills/repo-intake-and-plan/references/repo-scan-rules.md

## Conservative behavior - prefer explicit README evidence over filename guesses - mark guessed classifications as inferred - record ambiguity instead of overcommitting

This directly aligns with the third item in SKILL.md's 'When to apply': 'When inference, evaluation, and training candidates must be classified conservatively.', with both rules mutually reinforcing each other.

Role boundaries are strictly enforced: it only scans and plans, without installing environments, downloading large assets, executing substantive commands, or making high-risk patching decisions; it delivers the minimal trustworthy reproduction recommendation to the main orchestrator.

skills/repo-intake-and-plan/SKILL.md

## Clear boundaries - This skill scans and plans. - This skill is helper-tier and should usually be orchestrator-invoked. - It does not install environments. - It does not prepare large assets. - It does not execute substantive reproduction commands. - It does not decide high-risk patching.

'Output expectations' further standardizes deliverables: repository structure summary, documented command manifest, inference/evaluation/training/other classifications, minimal trustworthy reproduction recommendations, and an ambiguity/risk register.

The orchestrator genuinely invokes these two scripts (they are not mere documentation decorations): orchestrate_repro.py resolves the skill directory and executes scan_repo.py --repo … --json as a subprocess, then passes the resulting readme_path to extract_commands.py --readme … --json, integrating the output into the reproduction workflow.

skills/ai-research-reproduction/scripts/orchestrate_repro.py

scan_data = run_json(scan_script, ["--repo", str(repo_path), "--json"]) readme_path = scan_data.get("readme_path") command_data: Dict[str, Any] = {"commands": [], "counts": {}, "warnings": []} if readme_path: command_data = run_json(extract_script, ["--readme", readme_path, "--json"])

The same script bundles these two files into _bundled/skills/repo-intake-and-plan/ (see source/target/sha256 entries in _bundled/MANIFEST.json), enabling the main skill to execute this stage even when installed independently; ai-research-explore's orchestrate_explore.py also reuses scan_repo.py.

2Core Capabilities

01Repository structure scanning (whitelisted key files + high-signal directories + top-level counts + missing component warnings)

02Extracting shell commands from README code blocks / `$ ` prompt lines, including backslash line-continuation merging and deduplication

03Command classification into inference / evaluation / training / other, with auxiliary kind tagging (setup/asset/smoke/run)

04Placeholder detection: commands containing angle-bracket placeholders like <PATH/TO/DATASET> are marked as non-runnable as-is

05Markdown structure awareness: inline code block # comments are not treated as headers, and bare > is not treated as a command prompt (preventing prose from being misinterpreted as commands)

06Entrypoint script structural verification → conditionally elevating command classification to training when justified (with evidence tags)

07Outputting minimal trustworthy reproduction recommendations + ambiguity/risk register for the main orchestrator

3External Dependencies

Kind	Dependency / Endpoint
cli	Python 3（脚本解释器；由宿主/编排器调用，脚本自身无子进程外呼）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Execute local script or command: python3 scripts/scan_repo.py --repo <path> --json (provided with this skill; read-only directory enumeration)

Audit Notes: Both scripts are read-only analyzers relying solely on the Python standard library: full-directory token scans for dangerous patterns (https?://, urllib, requests, socket, subprocess, os.environ, open( in write mode) returned zero hits; they do not access the network, read environment variables or credentials, write any files, or execute extracted commands. Path operations enforce relative-to-root validation, discarding out-of-bounds targets immediately. The only consideration is that it inspects text and limited source code from untrusted repositories: manifests and classifications could be influenced by a malicious README (e.g., disguising training commands as inference), but results serve strictly as advisory recommendations for human or orchestrator review prior to downstream authorization gates, warranting a green rating.

5Second-Pass Verification

[ok] skill 路径（任务书标『待定位』） — 实际相对路径 skills/repo-intake-and-plan；SKILL.md 位于该目录根。
[ok] 『helper 脚本』确实存在且被调用（非文档装饰） — orchestrate_repro.py:1162-1167 设定 scan_script/extract_script 并在 1173-1178 以 run_json(...) 执行；_bundled/MANIFEST.json 记录两文件打包目标与 sha256；references/skill-registry.json 的 required_files 列出两者。
[discrepancy] SKILL.md 未给出脚本调用示例 — SKILL.md 仅在 Notes 写 'Use `references/repo-scan-rules.md` and helper scripts under `scripts/`.'，没有给命令行/参数示例；实际 CLI 契约（--repo/--json、--readme/--json）只能从脚本 argparse 与编排器调用点得到。对模型自助调用不够友好，属可改进项；不影响机制结论，已在 capabilities/how_it_works 中改用编排器调用点为证据。
[ok] 无网络/无凭证/无写入 — 两脚本 import 仅 argparse/json/re/pathlib/datetime/typing（scan_repo 另有 timezone）；全目录 URL/urllib/requests/socket/subprocess/os.environ 扫描零命中；无写文件调用（仅 print 到 stdout）。
[ok] 路径越界防护 — referenced_python_script() 先 (root / path).resolve() 再 candidate.relative_to(root)，越界抛 ValueError 返回 None；并有 is_file() 与 524_288 字节上限。
[ok] 分类优先级与注释一致 — classify() 实际顺序为 setup/asset 前缀 → 章节语义 → SCRIPT_CATEGORY_HINTS → 关键词，与文件内注释 'Unambiguous setup/asset syntax outranks generic headings' 一致；command_kind() 独立返回 setup/asset/run/smoke（--help/-h → smoke）。
[ok] README 定位与姊妹 helper 分工 — README.md:160 'Two helpers support orchestration: `repo-intake-and-plan` and `paper-context-resolver`.'；tests/trigger_cases.json 中 'expected_top': 'repo-intake-and-plan' 的用例存在（repo_scan_only_en：'Do not run anything yet.'），与 SKILL.md 的『不执行实质命令』一致。
[ok] 元数据 — 本地 git HEAD bd91195ad73199b95e24532b581ff12c07dcce09（= 任务书 pin）；LICENSE MIT / Copyright (c) 2026 Chengkun Rao；gh api → stars 487、last_push 2026-09-13T13:16:25Z。

6Verdict & Scenarios

Command extraction is a verifiable deterministic pipeline rather than model hallucination: regex + line continuation merging + deduplication + header attribution, outputting structured category/kind and warnings.

Conservative and explainable classification: category escalation requires meeting structural evidence score thresholds and logs classification_source/classification_evidence, preventing training from masquerading as inference.

Rigorous input sanitization against untrusted repositories: placeholder detection, bare blockquote exclusion, ignoring # inside code blocks as headers, path-relative-to-root validation, and file size limits.

Genuinely integrated into orchestrators: both the main orchestrator and the explore variant execute these scripts, which are packaged into _bundled/ (with sha256 checksums), allowing standalone execution of this stage.

Clean operational boundaries: does not set up environments, download assets, execute commands, or write files; scanning results serve strictly as advisory inputs to downstream authorization stages.

Best for: Suitable as a prerequisite for any README-first AI/deep learning repository reproduction: scenarios where a reliable structural summary, a documented command manifest, and conservative classification of inference/evaluation/training entrypoints are required before taking action; especially suitable as the initial deterministic stage for reproduction orchestrators (ai-research-reproduction) or exploration pipelines (ai-research-explore), as well as for users wanting a 'README command health check' on their own repositories (using --json for machine-readable output).

Not for: Not suitable for scenarios requiring environment setup or weight downloads (use env-and-assets-bootstrap instead); not suitable when execution has already begun and a specific command needs running (use minimal-run-and-audit / run-train); not suitable for pure paper interpretation (use paper-context-resolver); not suitable as an end-to-end reproduction runner—it only scans and plans, without generating final reports.

Install Agent-Ready

① Verified Mirror 2026-09-15

Option A · Direct DownloadDownload repo-intake-and-plan.tar.gz

sha256: 1953a875072a9f35…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit bd91195ad7.