kotonoha 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.2] - 2026-09-29
+
+### Added
+
+- Add a mandatory rubber-duck review loop to `write` mode. Generated
+  documents are revised, structurally rechecked, and reviewed again until
+  no actionable findings remain.
+- Distinguish a missing independent reviewer (`review not performed`) from
+  a review that reaches its round limit with unresolved findings
+  (`review did not converge`).
+
+## [0.1.1] - 2026-09-28
+
+### Added
+
+- Add the `kotonoha install` CLI for installing `tech-writer` into a
+  project or user skill directory.
+- Add `--target` for selecting a skill directory and `--force` for
+  explicitly replacing an existing installation.
+- Add automated tests for default installation, overwrite protection,
+  forced replacement, and installation from the packed npm artifact.
+
+### Changed
+
+- Document separate npm and source-checkout installation workflows in the
+  README.
+
+## [0.1.0] - 2026-09-28
+
+### Added
+
+- Publish the initial `tech-writer` skill for structuring README files,
+  design documents, API references, PR and issue text, release notes,
+  user manuals, code comments, and Qiita and Zenn articles.
+- Add structural linting for headings, code fences, placeholders, and
+  suspicious links.
+
+[0.1.2]: https://github.com/nahisaho/kotonoha/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/nahisaho/kotonoha/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/nahisaho/kotonoha/releases/tag/v0.1.0

package/README.md

@@ -22,6 +22,10 @@ Japanese prose with natural-japanese.
   descriptions/commit messages/issue reports, release notes, user manuals,
   code comments, and Qiita/Zenn articles
 - Doctype-specific structure and checklists to guide writing
+- Iterative rubber-duck review after document creation, with fixes and
+  re-review until no actionable findings remain; unavailable reviews are
+  reported as `review not performed`, while unresolved review loops are
+  reported as `review did not converge`
 - `scripts/lint.py` for mechanical structural checks (heading-level skips,
   code blocks missing a language tag, leftover placeholders, suspicious
   links, etc.); pass `--atomic` for commit messages, PR descriptions, issue
@@ -39,7 +43,34 @@ Japanese prose with natural-japanese.
 - Python 3.9+ if you want to run the lint script (standard library only,
   no extra install needed)
 
-### Install
+### Install from npm
+
+Install the package, then copy `tech-writer` into a skill directory with
+the included CLI:
+
+```bash
+npm install --save-dev kotonoha
+npx kotonoha install
+```
+
+The default destination is `.github/skills/tech-writer` in the current
+project. To install into another supported skill directory, pass its parent
+directory:
+
+```bash
+npx kotonoha install --target .claude/skills
+npx kotonoha install --target ~/.copilot/skills
+```
+
+The command refuses to overwrite an existing `tech-writer` directory. Review
+or back up the existing installation, then pass `--force` only when you
+intend to replace it:
+
+```bash
+npx kotonoha install --force
+```
+
+### Install from a source checkout
 
 Inside this repository, the skill is already placed at
 `.github/skills/tech-writer`, so no extra setup is needed to use it with

package/bin/kotonoha.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const packageJson = require("../package.json");
+
+function printUsage() {
+  console.log(`Usage:
+  kotonoha install [--target <directory>] [--force]
+
+Options:
+  --target <directory>  Skill directory root (default: .github/skills)
+  --force               Replace an existing tech-writer installation
+  --help                 Show this help
+  --version              Show the installed kotonoha version`);
+}
+
+function fail(message) {
+  console.error(`kotonoha: ${message}`);
+  process.exitCode = 1;
+}
+
+function parseInstallOptions(args) {
+  let target = ".github/skills";
+  let force = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+
+    if (argument === "--force") {
+      force = true;
+      continue;
+    }
+
+    if (argument === "--target") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error("--target requires a directory");
+      }
+      target = value;
+      index += 1;
+      continue;
+    }
+
+    if (argument.startsWith("--target=")) {
+      const value = argument.slice("--target=".length);
+      if (!value) {
+        throw new Error("--target requires a directory");
+      }
+      target = value;
+      continue;
+    }
+
+    throw new Error(`unknown option: ${argument}`);
+  }
+
+  return { target, force };
+}
+
+function install(args) {
+  let options;
+  try {
+    options = parseInstallOptions(args);
+  } catch (error) {
+    fail(error.message);
+    return;
+  }
+
+  const source = path.resolve(__dirname, "..", "skills", "tech-writer");
+  const targetRoot = path.resolve(process.cwd(), options.target);
+  const destination = path.join(targetRoot, "tech-writer");
+
+  if (!fs.existsSync(source)) {
+    fail(`packaged skill not found at ${source}`);
+    return;
+  }
+
+  if (fs.existsSync(destination)) {
+    if (!options.force) {
+      fail(
+        `${destination} already exists; rerun with --force to replace it`,
+      );
+      return;
+    }
+    fs.rmSync(destination, { recursive: true, force: true });
+  }
+
+  fs.mkdirSync(targetRoot, { recursive: true });
+  fs.cpSync(source, destination, { recursive: true });
+  console.log(`Installed tech-writer to ${destination}`);
+}
+
+const [command, ...args] = process.argv.slice(2);
+
+if (command === "install") {
+  install(args);
+} else if (command === "--version" || command === "-v") {
+  console.log(packageJson.version);
+} else if (command === "--help" || command === "-h" || command === undefined) {
+  printUsage();
+} else {
+  fail(`unknown command: ${command}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kotonoha",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A GitHub Copilot CLI skill for structuring and polishing technical documents.",
   "license": "MIT",
   "author": "nahisaho",
@@ -12,6 +12,15 @@
     "url": "https://github.com/nahisaho/kotonoha/issues"
   },
   "homepage": "https://github.com/nahisaho/kotonoha#readme",
+  "bin": {
+    "kotonoha": "bin/kotonoha.js"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
   "keywords": [
     "copilot",
     "github-copilot",
@@ -21,6 +30,8 @@
     "markdown"
   ],
   "files": [
+    "CHANGELOG.md",
+    "bin/",
     "skills/"
   ]
 }

package/skills/tech-writer/SKILL.md

@@ -62,9 +62,12 @@ first, then hand Japanese prose to natural-japanese for polish.
 Infer the mode from the argument or the request:
 
 - `write` (default): new document, or restructuring a draft. Runs the full
-  §1–§4 workflow, starting with the intake loop in §1.
+  §1–§5 workflow, starting with the intake loop in §1 and ending only after
+  the rubber-duck review loop has no remaining actionable findings. If an
+  independent review cannot run or cannot converge, returns the explicit
+  review status required by §5 instead of claiming a clean review.
 - `review`: structural review of an existing document. Does not rewrite;
-  reports the gap against the doctype checklist (§5).
+  reports the gap against the doctype checklist (§6).
 - `score`: structure-only quick diagnostic. Runs
   `scripts/lint.py --json <file>` and summarizes the findings (no rewrite).
 
@@ -110,7 +113,7 @@ hand the user a checklist to fill in. Instead:
    one-line note) and move on.
 6. **Once complete, do not ask the user to compose anything.** Synthesize
    the gathered answers into the best possible generation approach yourself
-   and immediately continue into §2–§4 in the same turn to produce the
+   and immediately continue into §2–§5 in the same turn to produce the
    document. Skip further confirmation unless the doctype is release-facing
    and consequential (e.g. a public release note with breaking changes) or
    the user explicitly asked to see a plan first.
@@ -221,7 +224,51 @@ step 2 as the primary check for those.
 4. **Reader-goal recheck**: confirm the "what the reader can do after
    reading" outcome from §1 is actually achievable from this document alone.
 
-## 5. Doctype checklist summary
+## 5. Rubber-duck review loop — write mode only
+
+After the structural review in §4, use the host's subagent mechanism to
+launch an independent reviewer in the `rubber-duck` role to challenge the
+completed document for meaningful problems that the authoring pass may have
+missed. Prefer a registered `rubber-duck` agent when the host provides one;
+otherwise use an independent general-purpose or critic-style subagent with
+the same review prompt. Treat the reviewer as unavailable only when the host
+has no independent subagent mechanism. Do not substitute the author's own
+self-review: independence is the point of this pass. This loop is mandatory
+for `write` mode; do not run it for `review` or `score` mode.
+
+1. **Start the review with full context**: give the reviewer the target file,
+   doctype, intended reader, one-sentence reader outcome from §1, and any
+   explicit constraints or assumptions. Ask it to report concrete,
+   actionable problems in correctness, logic, missing information, reader
+   flow, examples, and stated limitations — not cosmetic preferences.
+2. **Resolve every valid finding**: edit the document rather than merely
+   listing proposed fixes. If a finding conflicts with a stated requirement
+   or is factually inapplicable, record a one-line reason for declining it.
+3. **Re-run the relevant checks after each edit round**: repeat the doctype
+   checklist and structural lint from §4 before asking for another
+   rubber-duck review. A fix must not introduce a new structural defect.
+4. **Review again with the prior decisions**: reuse the same reviewer context
+   when supported. Otherwise, include the previous findings, applied fixes,
+   and declined findings with their reasons in every new review prompt. Ask
+   specifically for unresolved or newly introduced actionable findings.
+5. **Use a bounded convergence rule**: allow at most five rubber-duck rounds
+   for a living, multi-section document. For an atomic artifact, run one
+   round and finish immediately if it is clean; only continue after an
+   actionable finding, with a maximum of three rounds. A round is clean only
+   when no unaddressed actionable correctness, logic, completeness,
+   reader-flow, example, or limitation findings remain. A finding declined
+   with a recorded requirement-based or factual reason is a resolved
+   exception rather than an open finding. If another round runs, supply that
+   exception back to the reviewer under step 4. Purely cosmetic preferences
+   are not actionable.
+6. **Report non-clean outcomes precisely**: if the host has no independent
+   reviewer, label the result `review not performed` and do not claim the
+   rubber-duck pass completed. If the round limit is reached with
+   unaddressed actionable findings, or findings oscillate between
+   contradictory requirements, label it `review did not converge` and
+   include the latest unresolved findings and fixes already attempted.
+
+## 6. Doctype checklist summary
 
 See each reference file for detail. The items below are for living,
 multi-section documents (README, design doc, API reference, release notes,