harness-generate-iOS

Auto-generate the full Claude Code harness for an iOS project (CLAUDE.md, docs/, README quick-cards, .claude/rules/). Default scans the entire project; pass...

Security Scan

The skill's purpose (generate an iOS Claude harness) generally matches its instructions, but there are inconsistencies and a prompt-injection signal: it expects macOS/Xcode tooling and broad repository read/write without declaring platform/binary requirements, and the SKILL.md contains unicode control characters that can hide or obfuscate instructions.

Purpose & Capability

The skill claims to auto-generate an iOS harness and the SKILL.md describes full-repo scans and file generation — that matches. However, the metadata declares no required binaries or OS restrictions while the instructions explicitly rely on macOS/Xcode tooling (xcodebuild, reading .xcodeproj/.xcworkspace, pbxproj parsing) and common CLI tools (grep, bash/Glob). The lack of declared OS/binary requirements is an incoherence: a consumer would realistically need Xcode/macOS and those binaries to run correctly.

Instruction Scope

The instructions ask the agent to scan the entire repository (glob/grep/Read various project files), generate and merge docs, update .claude/rules/, and write CLAUDE.md and other files. That's in-scope for the stated purpose but broad in reach (reads all files) and includes a mandatory task protocol and a step that says 'write Memory'. Additionally, the SKILL.md contains detected unicode control characters (prompt-injection pattern) which can hide or alter instructions — this raises concern about hidden or obfuscated behavior in the runtime instructions.

Install Mechanism

This is an instruction-only skill with no install spec or bundled code, which minimizes installation risk (nothing is downloaded or written by an installer).

Credentials

No environment variables or credentials are requested, which is proportionate. However, the skill will scan repository contents and could therefore read embedded secrets (API keys, passwords, provisioning profiles) present in the project — the SKILL.md's QUALITY.md explicitly calls out 'no sensitive information submission', but that is guidance, not an enforcement mechanism. Also, the skill does not declare needing Xcode/CLI tooling, which is an omitted requirement rather than an extra credential demand.

Persistence & Privilege

The skill does not request permanent platform privileges (always: false) and does not modify other skills. It does instruct creating/overwriting generated files in docs/, CLAUDE.md, and .claude/rules/ and to 'write Memory' as part of Phase 6 — this is expected for a generator but means it will persist changes into the repo and agent memory. Because autonomous invocation is enabled by default, consider the combination of repository-write behavior + automatic invocation potential if you allow autonomous runs.

Scan Findings in Context

[unicode-control-chars] unexpected: Pre-scan detected unicode control characters within SKILL.md. These characters can be used to obfuscate or inject hidden instructions; they are not necessary for a straightforward harness generator and warrant manual inspection of the SKILL.md and the template files to ensure no hidden directives or altered text.

What to consider before installing

Before installing or running this skill: 1) Review SKILL.md and the referenced templates/scan-procedures files manually (look for hidden characters and confirm all directives are clear). 2) Run it in a sandbox or separate branch — it will read the entire repo and write files (docs/, CLAUDE.md, .claude/rules/), so you should review diffs before committing. 3) Ensure you're on macOS with Xcode/xcodebuild and standard CLI tools available — the skill assumes these but does not declare them. 4) Check the repository for embedded secrets (API keys, provisioning profiles); the generator may surface them in outputs — remove or redact secrets before generating. 5) If you allow autonomous invocation, restrict the agent's repository write permissions or require manual approval of generated changes. If you want higher assurance, ask the author to explicitly declare required binaries/OS and to remove or explain any unicode control characters in SKILL.md.

iOS Generate Harness

Scan an iOS project and auto-generate the Claude Code harness file system. Core principle: CLAUDE.md is a map, not an encyclopedia — it holds only pointers and hard constraints; details live in docs/, READMEs, and .claude/rules/.

Arguments

• None (default): Full project initialization — generate the complete harness
• <module-path>: Process a single module (e.g. Packages/SomeKit, App/LoginModule)

Routing: if an argument is provided and is not --init → single-module mode; otherwise → full-project mode.

---

Execution Protocol (Mandatory)

All multi-step flows MUST create a task list via TaskCreate and execute step by step.

Why

• Models tend to skip or forget steps when processing long instructions
• Task lists provide visible progress — users can track what's done
• Each task must be marked completed before moving to the next, preventing skipped steps
• If something fails, the exact failing task is identifiable

How

1. After reading this skill, the first action MUST be TaskCreate for all Phase tasks
2. Before starting each task → TaskUpdate(status: "in_progress")
3. After completing each task → TaskUpdate(status: "completed")
4. Before starting the next task → TaskList to confirm the previous task is completed
5. If a task fails → keep it in_progress, fix the issue, then mark completed

Task Template (Full Project)

When running Full Project Initialization, MUST create these tasks (in order):

Task 1: [Phase 1] Scan project structure
Task 2: [Phase 2] Generate docs/ files
Task 3: [Phase 3] Process each module (README + rules)
Task 4: [Phase 4] Generate CLAUDE.md
Task 5: [Phase 5] Cross-validation
Task 6: [Phase 6] Summary output + write Memory

Task Template (Single Module)

When running Single Module Flow, MUST create these tasks:

Task 1: Scan module {module-name}
Task 2: Generate README quick-card
Task 3: Evaluate and generate Rule file
Task 4: Update indexes (CLAUDE.md + parent package README)
Task 5: Cross-validation

---

Full Project Initialization

Phase 1: Scan Project Structure

Read scan-procedures.md for extraction methods. Collect:

1. Project metadata: workspace filename, scheme list, iOS deployment target
2. Dependencies: CocoaPods pod list, SPM package list
3. Compiler flags: #if macro names → identify dual/multi-target structure
4. SwiftLint rules: error-level rule list
5. Module inventory: SPM packages under Packages/ + business modules under the main directory
6. Architecture pattern: infer from file naming and imports (MVVM / MVP / MVC / Coordinator etc.)

Run all scans in parallel (multiple Glob/Grep calls or Agent sub-tasks).

Phase 2: Generate docs/

Generate each file per templates.md templates. Prepend <!-- AUTO-GENERATED, review and edit --> to every file.

File	Data source	Scan method
ARCHITECTURE.md	import statements → dependency graph; directory structure → layering	see scan-procedures.md "Architecture inference"
PITFALLS.md	swiftlint:disable comments + force unwrap/cast scan	see scan-procedures.md "Dangerous patterns"
STYLE.md	file naming patterns + directory structure + localization detection	see scan-procedures.md "Naming & style detection"
QUALITY.md	fixed template, tweaked per detected toolchain	use template directly
SCRIPTS.md	Scripts/ directory scan + Makefile + fastlane	see scan-procedures.md "Script discovery"

Existing file handling: if a same-named file already exists in docs/, read it and merge — do not overwrite. Use <!-- AUTO-GENERATED --> markers to distinguish generated vs. hand-written content.

Phase 3: Process Each Module

Run the "Single Module Flow" (below) for every module discovered in Phase 1.

Order:

1. SPM packages under Packages/ first (skip packages with only Package.swift and no .swift source files)
2. Then business modules under the main directory

Parallelism: multiple modules can be processed concurrently via Agent sub-tasks, but within a single module README and rule generation must be sequential (rule depends on README analysis).

Phase 3 completion criteria (ALL must be met to mark task completed):

• Every module with source code has a README
• Skipped modules (e.g. empty packages) have documented reasons

Phase 4: Generate CLAUDE.md

Fill the "CLAUDE.md skeleton" template from templates.md with Phase 1 scan data + Phase 3 module outputs.

At this point all READMEs and rule files already exist, so CLAUDE.md can be written once with complete routing.

Fill rules:

• Quick Reference: direct scan results from Phase 1
• Task Routing: checklist-group format; one entry per README created in Phase 3, plus rule file auto-load annotations
• Key Rules: translate SwiftLint error-level rules to human-readable constraints + hard constraints found by code scanning (e.g. force-unwrap ban)
• Build & Compile: infer commands from workspace + scheme names; if multiple schemes, state when to build which
• Verification Loop: use fixed template

Constraint: final CLAUDE.md < 80 lines. If over, trim Key Rules to error-level only.

Phase 5: Cross-Validation (Mandatory)

After all files are generated and before the summary output, run these cross-validation checks. Any failure must be fixed before marking this task completed.

Check 1: README → CLAUDE.md reference completeness

For each newly created/updated Packages/*/README.md:
  - Does CLAUDE.md task routing have a corresponding checklist entry?
  - Missing → immediately add to the appropriate task routing group

Check 2: Rule → CLAUDE.md annotation completeness

For each newly created .claude/rules/*.md:
  - Does CLAUDE.md annotate "auto-loads .claude/rules/xxx.md"?
  - Missing → add annotation after the corresponding task routing entry

Check 3: CLAUDE.md path validity

For all [text](path) links in CLAUDE.md:
  - Does the path target actually exist?
  - Missing → remove the reference or annotate <!-- TODO: create this file -->

Check 4: Rule paths coverage accuracy

For each .claude/rules/*.md paths field:
  - Does the glob pattern match the expected files?
  - No matches → fix the pattern

Phase 6: Summary Output

List all generated/updated files in a table:

| File | Status | Lines |
|------|--------|-------|
| CLAUDE.md | created | 72 |
| docs/ARCHITECTURE.md | created | 45 |
| Packages/XXX/README.md | updated | 28 |
| .claude/rules/xxx.md | created | 12 |

Prompt the user to review all files marked <!-- AUTO-GENERATED -->.

---

Single Module Flow

Step 1: Scan Module

Use the "Swift code scanning" methods from scan-procedures.md. Collect:

├── public/open type list (name + one-line responsibility)
├── singletons (shared instances)
├── delegate/protocol definitions
├── async methods
├── import dependency list
└── existing README.md and .claude/rules/ content

Step 2: Generate README Quick-Card

Use the "README quick-card" template from templates.md.

Must include:

• Module name + one-line description (infer purpose from class/method names)
• API index table (public/open types only, one-line responsibility each)
• Constraints (hard constraints that cause crashes or bugs)
• Anti-patterns (real mistakes or highly common errors)

Optional:

• Usage examples: only when the API is non-obvious (builder pattern, chaining, etc.)
• Dependency notes: only when dependencies are non-obvious

Never write: full method signatures, parameter type details, changelog, installation instructions.

Constraint: 20–40 lines. If over, merge similar types in the API index and drop optional sections.

Existing README handling: if the module already has a README.md, read it and preserve hand-written content; only add missing sections.

Step 3: Decide Whether a Rule Is Needed

Check each condition — generate a rule if any is met:

Condition	Detection method	Example rule content
Call-order constraint	Has configure/setup + start/begin method pairs	"Call configure before start"
Thread constraint	Has @MainActor or UI class with async methods	"UI updates must be on main thread"
Easy-to-misuse API	Method names contain unsafe/force, or parameters include Bool toggles	"Do not call unsafeXxx directly"
Design token constraint	Module is a UI component library	"Colors/fonts must use semantic tokens"
Compiler flag divergence	Files contain #if TARGET_A/#if TARGET_B	"Build both schemes when modifying"

None met → do not generate a rule file.

Generated rules use the "Rule file" template from templates.md: < 15 lines, imperative sentences.

Step 4: Update Indexes

• If the module belongs to an umbrella package (e.g. UIComponents sub-component) → update that package's README index table
• MUST add a CLAUDE.md task routing entry for every newly created README
• MUST annotate the auto-load relationship in CLAUDE.md for every newly created rule file

---

Output Constraints

File type	Line limit	Over-limit strategy
CLAUDE.md	80 lines	Trim Key Rules to error-level only
README quick-card	40 lines	Merge similar types, drop optional sections
Rule file	15 lines	Merge similar rules
docs/ files	No hard limit	Keep concise, avoid duplication

Path Validation

• All reference paths in generated files must point to real, existing files
• After generation, verify every [link](path) target exists
• Missing targets → remove the reference or annotate <!-- TODO: create this file -->

---

Post-Generation: Write Memory

After all files are generated, write or update a single memory entry to guide Claude's daily behavior when maintaining the harness. This memory teaches Claude how to use the harness structure, which CLAUDE.md itself cannot express.

Memory file: feedback_harness_maintenance.md

---
name: Harness maintenance rules
description: How to maintain the harness structure when adding rules, modules, or fixing bugs — keep CLAUDE.md as an index, put details in docs/
type: feedback
---

新增规则/规范时，按 CLAUDE.md 任务路由找对应 docs/ 文件写入，不要直接改 CLAUDE.md。
新增模块时补 README 速查卡，有硬约束时补 .claude/rules/。

**Why:** CLAUDE.md 是索引入口，具体内容分散在 docs/、README、rules 中。直接往 CLAUDE.md 塞内容会破坏分层。

**How to apply:**
1. 用户让记录规则 → 查任务路由确定归属文件
2. 新建模块 → 补 README（20-40 行）+ 按需补 rule（< 15 行）
3. 改完代码 → 执行 Verification Loop

If a memory with similar content already exists (e.g. feedback_docs_harness.md), update it in-place rather than creating a duplicate. Update MEMORY.md index accordingly.