Harden adoption workflow and open-source packaging

Author: oceanusXXD

CHANGELOG.md

@@ -12,7 +12,13 @@ Detailed notes for each tagged release live under [`docs/releases/`](./docs/rele
 - Added OpenAI-compatible Responses endpoint configuration through `CODE2SKILL_OPENAI_BASE_URL`.
 - Improved Skill planning and writing prompts to avoid documentation/packaging-only pseudo-skills and produce more maintainer-oriented guidance.
 - Improved PyPI-facing README content, package metadata, and sdist documentation inclusion.
+- Added explicit user personas and business scenarios to README/use-case documentation.
+- Hardened `adapt` to reject incomplete generated Skill directories before writing target files.
+- Hardened `doctor --target cursor` to require the copy manifest used for stale generated-rule cleanup.
+- Hardened CLI environment variable parsing to report invalid values instead of silently falling back to defaults.
+- Restricted sdist docs inclusion to public docs and release notes, excluding internal planning docs.
 - Fixed cost-estimate assumption text that rendered as mojibake in CLI/report output.
+- Fixed LLM invalid-JSON responses to produce a clear runtime error.
 - Fixed incremental generation to replan when affected Skills are missing from the existing plan.
 
 ## v0.1.7

CONTRIBUTING.md

@@ -13,12 +13,15 @@ python -m pip install -e .[dev]
 
 Run these before opening a pull request:
 
-```bash
+```powershell
+if (Test-Path dist) { Remove-Item -Recurse -Force dist }
 python -m pytest -q
-python -m build
+python -m build --sdist --wheel
 python -m twine check dist/*
 ```
 
+On non-Windows shells, use `rm -rf dist` before the build.
+
 ## Repository Areas
 
 - `src/code2skill/`: production package code
@@ -31,6 +34,7 @@ python -m twine check dist/*
 - keep changes scoped and reviewable
 - add or update tests for behavior changes
 - update docs when command behavior, API shape, or release process changes
+- for user-facing changes, state the target persona and business scenario being improved
 - update `CHANGELOG.md` and add `docs/releases/vX.Y.Z.md` when preparing a release
 
 ## Release Update Steps

MANIFEST.in

@@ -2,7 +2,9 @@ include LICENSE
 include README.md
 include README.zh-CN.md
 include CHANGELOG.md
-recursive-include docs *.md
+include docs/*.md
+recursive-include docs/releases *.md
+prune docs/superpowers
 recursive-include src/code2skill py.typed
 prune .code2skill
 prune tests

README.md

@@ -21,6 +21,25 @@ Use it when a Python project needs AI coding assistants to understand current mo
 - Validates generated bundles and adapted tool files with `doctor`.
 - Supports OpenAI Responses API, OpenAI-compatible Responses endpoints, Claude, and Qwen.
 
+## Who Uses It
+
+| User profile | What they need | How code2skill helps |
+|---|---|---|
+| Python maintainers | AI assistants that respect current module boundaries and extension patterns | Generates evidence-backed Skills from source code and keeps them reviewable |
+| DevEx and platform teams | A repeatable way to standardize AI coding context across many repositories | Exposes CLI, Python API, CI refresh, and readiness checks |
+| Open-source maintainers | Contributor-facing AI instructions that can be audited like normal docs | Writes committed artifacts and target files instead of relying on private chat history |
+| AI tooling evaluators | One repository knowledge layer that works across several assistants | Publishes the same Skills to Codex, Claude Code, Cursor, GitHub Copilot, and Windsurf |
+
+## Business Scenarios
+
+| Scenario | Trigger | Success signal |
+|---|---|---|
+| First AI adoption | A repository starts using Codex, Cursor, Claude Code, Copilot, or Windsurf | `scan`, `adapt`, and `doctor` produce a ready target file |
+| PR knowledge refresh | Code changes may invalidate existing AI instructions | `ci --mode auto` reports affected files and affected Skills |
+| Multi-tool rollout | A team uses more than one AI coding assistant | `adapt --target all` writes consistent target outputs |
+| Platform automation | A DevEx team runs repository-knowledge checks across many services | Python API returns structured results and readiness status |
+| Open-source contributor onboarding | New contributors need implementation rules before changing code | Generated Skills and README/docs explain the repo's working contracts |
+
 ## Install
 
 Requires Python 3.10 or newer.

README.zh-CN.md

@@ -21,6 +21,25 @@ English documentation: [README.md](https://github.com/oceanusXXD/code2skill/blob
 - 用 `doctor` 校验 bundle、Skill plan、state 和目标工具文件是否可用。
 - 支持 OpenAI Responses API、OpenAI-compatible Responses endpoint、Claude 和 Qwen。
 
+## 用户画像
+
+| 用户画像 | 需要什么 | code2skill 如何帮助 |
+|---|---|---|
+| Python 仓库维护者 | AI 助手遵守当前模块边界和扩展方式 | 从源码证据生成可审阅 Skills |
+| DevEx 和平台团队 | 在多个仓库中标准化 AI 编程上下文 | 提供 CLI、Python API、CI 刷新和可用性校验 |
+| 开源维护者 | 像审阅普通文档一样审阅 contributor-facing AI 说明 | 把知识写入可提交文件，而不是留在私有聊天记录 |
+| AI tooling 评估者 | 一套仓库知识发布到多个 AI 助手 | 同一套 Skills 可适配 Codex、Claude Code、Cursor、GitHub Copilot 和 Windsurf |
+
+## 业务场景
+
+| 场景 | 触发条件 | 成功信号 |
+|---|---|---|
+| 首次 AI 接入 | 仓库开始使用 Codex、Cursor、Claude Code、Copilot 或 Windsurf | `scan`、`adapt`、`doctor` 产出 ready 的目标文件 |
+| PR 知识刷新 | 代码改动可能让 AI 说明过期 | `ci --mode auto` 报告 affected files 和 affected Skills |
+| 多工具 rollout | 团队同时使用多个 AI 编程助手 | `adapt --target all` 写出一致的目标工具文件 |
+| 平台自动化 | DevEx 团队跨多个服务运行仓库知识检查 | Python API 返回结构化结果和 readiness |
+| 开源 contributor onboarding | 新贡献者改代码前需要项目实现规则 | 生成的 Skills 和 README/docs 明确仓库工作契约 |
+
 ## 安装
 
 需要 Python 3.10 或更高版本。

docs/use-cases.md

@@ -1,12 +1,21 @@
 # Use Cases
 
-`code2skill` is designed around three practical adoption scenarios for Python repositories.
+`code2skill` is built for maintainers who want AI coding assistants to work from the same repository knowledge that humans can review in Git.
 
-## 1. First Repository Knowledge Layer
+## Primary Personas
 
-### Problem
+| Persona | Repository pain | Desired outcome |
+|---|---|---|
+| Python maintainer | AI tools miss local boundaries, style, and workflow contracts | Generated Skills describe how to modify the current codebase |
+| DevEx or platform owner | Each team writes different AI rules, often by hand | One repeatable workflow standardizes assistant context across services |
+| Open-source maintainer | Contributors bring different tools and private chat context | Public, committed AI instructions make project expectations auditable |
+| AI tooling evaluator | A repository needs to compare Codex, Cursor, Claude Code, Copilot, and Windsurf | One Skill layer can be adapted into every supported target |
 
-AI coding assistants enter a repository with incomplete context. They read README files, scattered docs, previous code, and chat history, but those sources are not structured as stable implementation guidance.
+## Scenario 1: First Repository Knowledge Layer
+
+### Trigger
+
+A Python repository is adopting an AI coding assistant and needs a durable project entry point.
 
 ### Workflow
 
@@ -18,22 +27,22 @@ code2skill adapt . --target codex
 code2skill doctor . --target codex
 ```
 
-### Output
+### Outputs
 
 - `.code2skill/adoption-guide.md`
 - `.code2skill/skills/index.md`
 - `.code2skill/skills/*.md`
 - `AGENTS.md` or another target instruction file
 
-### Business Value
+### Success Signal
 
-The team gets a reviewable AI-facing project entry point that can be committed and maintained like normal repository documentation.
+`doctor` reports `ready: true`, generated Skills are reviewable, and the target instruction file can be committed.
 
-## 2. Pull Request And CI Refresh
+## Scenario 2: Pull Request And CI Refresh
 
-### Problem
+### Trigger
 
-AI-facing project knowledge becomes stale when code changes. Manually updating tool-specific rules is easy to skip, and full regeneration on every PR can be wasteful.
+Code changes may invalidate existing AI-facing project knowledge.
 
 ### Workflow
 
@@ -43,22 +52,22 @@ code2skill adapt . --target codex
 code2skill doctor . --target codex
 ```
 
-### Output
+### Outputs
 
 - refreshed Skill files when affected
 - refreshed target instruction files
-- `.code2skill/report.json` showing mode, changed files, affected files, affected Skills, and written artifacts
+- `.code2skill/report.json` with execution mode, changed files, affected files, affected Skills, and written artifacts
 - `.code2skill/state/analysis-state.json` for later incremental reuse
 
-### Business Value
+### Success Signal
 
-Teams can make AI knowledge maintenance part of the normal PR loop, with clear evidence for what changed and why.
+The PR shows exactly which AI-facing artifacts changed and why.
 
-## 3. One Knowledge Source For Multiple AI Tools
+## Scenario 3: One Knowledge Source For Multiple AI Tools
 
-### Problem
+### Trigger
 
-Codex, Claude Code, Cursor, GitHub Copilot, and Windsurf all expect different instruction-file locations or formats. Maintaining each by hand creates drift.
+A team uses more than one AI coding assistant and wants consistent project context across tools.
 
 ### Workflow
 
@@ -68,23 +77,23 @@ code2skill adapt . --target all
 code2skill doctor . --target all
 ```
 
-### Output
+### Outputs
 
 - `AGENTS.md`
 - `CLAUDE.md`
 - `.cursor/rules/*`
 - `.github/copilot-instructions.md`
 - `.windsurfrules`
 
-### Business Value
+### Success Signal
 
-The repository owns one generated Skill layer and publishes consistent context to every supported assistant.
+All supported target files are generated from the same Skill layer, and `doctor --target all` reports readiness.
 
-## 4. Platform Or DevEx Automation
+## Scenario 4: Platform Or DevEx Automation
 
-### Problem
+### Trigger
 
-Platform teams may need to run the same repository-knowledge workflow across multiple Python services without shelling out manually.
+A platform team needs to run the same repository-knowledge workflow across multiple Python services.
 
 ### Workflow
 
@@ -99,9 +108,29 @@ for repo in repositories:
         raise RuntimeError((repo, readiness.next_steps))
 ```
 
-### Business Value
+### Success Signal
+
+Automation can make a binary decision from structured readiness data instead of scraping free-form command output.
+
+## Scenario 5: Open-Source Contributor Onboarding
+
+### Trigger
+
+An open-source project wants new contributors and AI assistants to share the same implementation rules before a change is proposed.
+
+### Workflow
+
+```bash
+code2skill scan . --llm qwen --model qwen-plus-latest
+code2skill adapt . --target codex
+code2skill doctor . --target codex
+```
+
+Then link the generated target file and `.code2skill/skills/index.md` from contributor documentation.
+
+### Success Signal
 
-The same workflow can be embedded into internal automation while preserving the same artifact layout and readiness checks as the CLI.
+Contributors can inspect the same AI-facing project guidance that maintainers review and commit.
 
 ## Selection Guide
 
@@ -111,3 +140,4 @@ The same workflow can be embedded into internal automation while preserving the
 | PR refresh | `ci --mode auto` | `adapt` | `doctor` |
 | Multi-tool publishing | `scan` | `adapt --target all` | `doctor --target all` |
 | Platform automation | Python API | `run_ci`, `adapt_repository` | `doctor` |
+| Open-source onboarding | `scan` | docs link plus `adapt` | `doctor` |

pyproject.toml

@@ -57,6 +57,8 @@ Repository = "https://github.com/oceanusXXD/code2skill"
 Documentation = "https://github.com/oceanusXXD/code2skill#readme"
 Issues = "https://github.com/oceanusXXD/code2skill/issues"
 Changelog = "https://github.com/oceanusXXD/code2skill/blob/main/CHANGELOG.md"
+Contributing = "https://github.com/oceanusXXD/code2skill/blob/main/CONTRIBUTING.md"
+Security = "https://github.com/oceanusXXD/code2skill/blob/main/SECURITY.md"
 
 [project.optional-dependencies]
 test = [

src/code2skill/adapt.py

@@ -21,6 +21,7 @@ def adapt_skills(
     source_path = _resolve_path(destination_root_path, source_dir)
     if not source_path.exists() or not source_path.is_dir():
         raise FileNotFoundError(f"Skill directory does not exist: {source_path}")
+    _validate_skill_source(source_path)
 
     written: list[Path] = []
     for target_definition in get_target_definitions(target):
@@ -39,6 +40,20 @@ def _resolve_path(root: Path, candidate: Path | str) -> Path:
     return (root / path).resolve()
 
 
+def _validate_skill_source(source_dir: Path) -> None:
+    index_path = source_dir / "index.md"
+    skill_files = [
+        path
+        for path in source_dir.glob("*.md")
+        if path.name != "index.md"
+    ]
+    if not index_path.is_file() or not skill_files:
+        raise ValueError(
+            "Generated skills directory is incomplete: expected index.md and at least "
+            "one Skill .md file. Run `code2skill scan .` without `--structure-only` first."
+        )
+
+
 def _copy_skills(source_dir: Path, destination_dir: Path) -> list[Path]:
     destination_dir.mkdir(parents=True, exist_ok=True)
     skill_files = sorted(source_dir.glob("*.md"))

src/code2skill/capabilities/adoption_service.py

@@ -285,11 +285,8 @@ def _check_target_outputs(repo_root: Path, target: str, skills_dir: Path) -> lis
             checks.append(_check_copy_target(definition.name, destination, skills_dir))
             continue
         else:
-            ok = (
-                destination.is_file()
-                and MANAGED_BLOCK_START in destination.read_text(encoding="utf-8")
-                and MANAGED_BLOCK_END in destination.read_text(encoding="utf-8")
-            )
+            content = destination.read_text(encoding="utf-8") if destination.is_file() else ""
+            ok = MANAGED_BLOCK_START in content and MANAGED_BLOCK_END in content
         checks.append(
             AdoptionCheck(
                 name=f"target_{definition.name}",
@@ -351,23 +348,32 @@ def _check_copy_target(name: str, destination: Path, skills_dir: Path) -> Adopti
         )
 
     manifest_path = destination / COPY_MANIFEST_NAME
-    if manifest_path.is_file():
-        try:
-            manifest_names = _read_copy_manifest(manifest_path)
-        except ValueError as exc:
-            return AdoptionCheck(
-                name=f"target_{name}",
-                status="invalid",
-                message=str(exc),
-                path=manifest_path,
-            )
-        if manifest_names != expected_names:
-            return AdoptionCheck(
-                name=f"target_{name}",
-                status="invalid",
-                message=f"{name} target manifest does not match current generated Skills.",
-                path=manifest_path,
-            )
+    if not manifest_path.is_file():
+        return AdoptionCheck(
+            name=f"target_{name}",
+            status="missing",
+            message=(
+                f"{name} target manifest is missing. Run `code2skill adapt . --target {name}` "
+                "so stale generated files can be tracked safely."
+            ),
+            path=manifest_path,
+        )
+    try:
+        manifest_names = _read_copy_manifest(manifest_path)
+    except ValueError as exc:
+        return AdoptionCheck(
+            name=f"target_{name}",
+            status="invalid",
+            message=str(exc),
+            path=manifest_path,
+        )
+    if manifest_names != expected_names:
+        return AdoptionCheck(
+            name=f"target_{name}",
+            status="invalid",
+            message=f"{name} target manifest does not match current generated Skills.",
+            path=manifest_path,
+        )
 
     return AdoptionCheck(
         name=f"target_{name}",

src/code2skill/cli.py

@@ -154,8 +154,8 @@ def build_parser() -> argparse.ArgumentParser:
 
 
 def main(argv: Sequence[str] | None = None) -> int:
-    parser = build_parser()
     try:
+        parser = build_parser()
         args = parser.parse_args(argv)
         return _run_command(parser, args)
     except KeyboardInterrupt:
@@ -334,20 +334,25 @@ def _print_stderr(message: str) -> None:
 
 
 def _env_choice(name: str, default: str, choices: tuple[str, ...]) -> str:
-    value = os.getenv(name, "").strip().lower()
+    raw_value = os.getenv(name)
+    if raw_value is None or not raw_value.strip():
+        return default
+    value = raw_value.strip().lower()
     if value in choices:
         return value
-    return default
+    raise ValueError(
+        f"{name} must be one of {', '.join(choices)}; got {raw_value!r}."
+    )
 
 
 def _env_int(name: str, default: int) -> int:
-    value = os.getenv(name, "").strip()
-    if not value:
+    raw_value = os.getenv(name)
+    if raw_value is None or not raw_value.strip():
         return default
     try:
-        return int(value)
+        return int(raw_value.strip())
     except ValueError:
-        return default
+        raise ValueError(f"{name} must be an integer; got {raw_value!r}.") from None
 
 
 def _env_optional(name: str) -> str | None: