feat/mock cli by hartmutobendorf · Pull Request #7 · canonical/cli-skill

hartmutobendorf · 2026-06-10T12:40:18Z

added skills
added cli help review command
updated workflow
updated workflow
looking for clis
small gh action improvement
small gh action improvement
small gh action improvement
small gh action improvement
Mock CLI added

github-actions · 2026-06-10T13:21:19Z

# CLI Standard Compliance Review — taskThing

1. Summary

Metric	Value
Commands assessed	5
High severity violations	7
Medium severity violations	4
Low severity violations	10
Overall Score	Need for Action (~-860 %)

Score calculation (per mandated algorithm):

N = 5 commands, W = 100 / 5 = 20 points per command.
High deduction per violation: 5 × 20 = 100 points. 7 High → -700.
Medium deduction per violation: 2 × 20 = 40 points. 4 Medium → -160.
Low deduction per violation: 0.5 × 20 = 10 points. 10 Low → -100.
Starting from 100 %: 100 - 700 - 160 - 100 = -860 %.

2. Compliance Matrix

Standard Clause	Rule Summary	Evidence	Status	Severity	Notes
Grammar + Vocabulary — "Commands are verbs. Every command that acts on a primary object of a command… must be a verb."	Commands must be verbs.	`addTodo` is a verb-noun compound, not a bare verb.	non-compliant	High	See Finding H1
Grammar + Vocabulary — "Commands are verbs…"	Commands must be verbs.	`readTodos` is a verb-noun compound, not a bare verb.	non-compliant	High	See Finding H7
Grammar + Vocabulary — "All commands in that second level must follow the rules outlined above."	Second-level commands must also be verbs.	`update todos` subcommand `todos` is a noun.	non-compliant	High	See Finding H5
Grammar + Vocabulary — "Consider using flags to prevent verb-noun-noun compounds…"	Avoid verb-noun-noun command names.	`remove-todo-item` is a three-part compound.	non-compliant	High	See Finding H4
Parameters, Flags and Options — Positional Parameters	Do not use positional parameters unless the order is natural and easily memorizable.	`addTodo title [place] [owner]` — three positionals with no natural directionality.	non-compliant	High	See Finding H2
Parameters, Flags and Options — Positional Parameters	Do not use positional parameters unless the order is natural and easily memorizable.	`remove-todo-item todo [extra]` — `extra` is arbitrary and undocumented in meaning.	non-compliant	High	See Finding H3
Parameters, Flags and Options — Positional Parameters	Do not use positional parameters unless the order is natural and easily memorizable.	`update todos todo [field] [value]` — three positionals with ambiguous semantics.	non-compliant	High	See Finding H6
Grammar + Vocabulary — "All commands must converge on a grammar based on the above rules."	Consistent grammar and naming conventions across all commands.	Mix of `addTodo`/`readTodos` (camelCase) and `remove-todo-item` (kebab-case).	non-compliant	Medium	See Finding M1
Parameters, Flags and Options — Flags accepting multiple arguments "Do not provide both forms."	Do not provide both repeatable singular flags and comma-separated plural flags.	`addTodo` has both `--tag` (repeatable) and `--tags` (comma-separated).	non-compliant	Medium	See Finding M2
Parameters, Flags and Options — Flags "As a policy, do not offer both short and long flags for the same action."	Avoid redundant flag aliases for the same action.	`addTodo` has `--prio` as an alias for `--priority`.	non-compliant	Medium	See Finding M3
Parameters, Flags and Options — Flags "As a policy, do not offer both short and long flags for the same action."	Avoid redundant flag aliases for the same action.	`update todos` has `--set-status` as an alias for `--status`.	non-compliant	Medium	See Finding M4
Parameters, Flags and Options — Flags "As a policy, do not offer both short and long flags for the same action."	Do not offer both short and long flags for the same action.	Root: `-v`/`--verbose`, `-q`/`--quiet`, `-f`/`--format`.	non-compliant	Low	See Findings L1–L3
Parameters, Flags and Options — Flags "As a policy, do not offer both short and long flags for the same action."	Do not offer both short and long flags for the same action.	`addTodo`: `-p`/`--priority`, `-t`/`--tag`.	non-compliant	Low	See Findings L4–L5
Parameters, Flags and Options — Flags "As a policy, do not offer both short and long flags for the same action."	Do not offer both short and long flags for the same action.	`remove-todo-item`: `-i`/`--id`, `-y`/`--yes`, `-F`/`--force`.	non-compliant	Low	See Findings L6–L8
Parameters, Flags and Options — Flags "As a policy, do not offer both short and long flags for the same action."	Do not offer both short and long flags for the same action.	`update todos`: `-s`/`--status`.	non-compliant	Low	See Finding L9
Parameters, Flags and Options — Flags "As a policy, do not offer both short and long flags for the same action."	Do not offer both short and long flags for the same action.	`readTodos`: `-a`/`--all`.	non-compliant	Low	See Finding L10
Feedback — "All tools should at a minimum support these flags: `--help`"	Minimum `--help` support required.	`--help` present on root and every subcommand.	compliant	n/a	n/a
Grammar + Vocabulary — "At most one sublevel may be used"	Allow at most one command sublevel.	Only `update` → `todos` uses a single sublevel.	compliant	n/a	Structure is compliant; subcommand naming is not
Parameters, Flags and Options — Flags with Values	Flag name and value must support separation by whitespace.	All flag arguments use whitespace separation.	compliant	n/a	n/a

3. Non-compliance Findings

H1 — `addTodo` is not a verb

Clause: "Commands are verbs. Every command that acts on a primary object of a command (e.g. snaps for snap, virtual machines for multipass) must be a verb."
Evidence:

add = commands.add_parser(
    "addTodo",
    help="Add a todo thing into the todo area",
    ...
)

Remediation: Rename to add (if todos are the primary object) or create-todo (verb-noun for a secondary object).

H2 — `addTodo` uses multiple ambiguous positional parameters

Clause: "Positional parameters are difficult for people to remember and use correctly, especially if they could be used interchangeably; do not use positional parameters unless the order is natural and easily memorizable."
Evidence:

add.add_argument("title", help="todo name")
add.add_argument("place", nargs="?", help="where it lives")
add.add_argument("owner", nargs="?", help="person maybe")

Remediation: Convert place and owner to named flags (e.g., --place, --owner). Keep title positional only if it is unambiguously the primary operand.

H3 — `remove-todo-item` contains an arbitrary second positional

Clause: Same positional parameter rule.
Evidence:

remove.add_argument("extra", nargs="?", help="second positional just because")

Remediation: Remove the extra positional. If secondary identifiers are needed, expose them as explicit flags (e.g., --name, --id).

H4 — `remove-todo-item` is a verb-noun-noun compound

Clause: "Consider using flags to prevent verb-noun-noun compounds, and e.g. use create-network --vmhost vmh1 nw1 over create-vmhost-network vmh1:nw1."
Evidence:

remove = commands.add_parser(
    "remove-todo-item",
    help="Remove, delete, or otherwise get rid of a todo",
    ...
)

Remediation: Flatten to remove (acting on the primary todo type) or delete-todo (verb-noun). Use flags for any additional disambiguation.

H5 — `update todos` subcommand is a noun, not a verb

Clause: "At most one sublevel may be used, and all commands in that second level must follow the rules outlined above." (commands are verbs)
Evidence:

update_commands = update.add_subparsers(dest="update_target")
update_todos = update_commands.add_parser(
    "todos",
    help="Update todo records in bulk or singular form",
)

Remediation: Rename the subcommand to a verb such as modify or edit, or eliminate the sublevel and expose the operation as a top-level verb like update-todo.

H6 — `update todos` uses multiple ambiguous positional parameters

Clause: Same positional parameter rule.
Evidence:

update_todos.add_argument("todo")
update_todos.add_argument("field", nargs="?", help="what to change")
update_todos.add_argument("value", nargs="?", help="new value maybe")

Remediation: Convert field and value to named flags (e.g., --field, --value).

H7 — `readTodos` is not a verb

Clause: "Commands are verbs. Every command that acts on a primary object of a command must be a verb."
Evidence:

read = commands.add_parser(
    "readTodos",
    help="Read todo information in one of several inconsistent ways",
    ...
)

Remediation: Rename to list (for all todos) or show (for a single todo), matching the Canonical shorthand conventions. For secondary objects, todos is acceptable as a shorthand listing command.

M1 — Inconsistent command naming conventions

Clause: "All commands must converge on a grammar based on the above rules."
Evidence:

commands.add_parser("addTodo", ...)        # camelCase
commands.add_parser("remove-todo-item", ...) # kebab-case
commands.add_parser("update", ...)           # single lowercase word
commands.add_parser("readTodos", ...)        # camelCase

Remediation: Adopt one convention for all multi-word commands (kebab-case is the prevailing convention in Canonical examples such as create-foo, delete-foo, update-foo).

M2 — `addTodo` provides both repeatable and comma-separated tag forms

Clause: "Do not provide both forms." (for flags accepting multiple arguments)
Evidence:

add.add_argument("-t", "--tag", action="append")
add.add_argument("--tags", help="comma separated tags")

Remediation: Choose one pattern. Prefer --tag (repeatable singular) or --tags (comma-separated plural), but not both.

M3 — `addTodo` provides an alternate long flag `--prio`

Clause: "As a policy, do not offer both short and long flags for the same action." (spirit: no redundant aliases for the same semantic action)
Evidence:

add.add_argument("-p", "--priority", dest="priority")
add.add_argument("--prio", dest="priority")

Remediation: Remove --prio. Keep only -p/--priority or --priority alone.

M4 — `update todos` provides an alternate long flag `--set-status`

Clause: "As a policy, do not offer both short and long flags for the same action."
Evidence:

update_todos.add_argument("-s", "--status")
update_todos.add_argument("--set-status")

Remediation: Remove --set-status. Keep only -s/--status.

L1 — Root `-v`/`--verbose`

Clause: "As a policy, do not offer both short and long flags for the same action."
Evidence:

parser.add_argument("-v", "--verbose", action="store_true", help="be extra talkative")

Remediation: Remove either -v or --verbose.